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This manual describes how to use the Plink86p/us linkage editor 
and program overlay manager. Information is organized here 85 


follows: 


Chapter 1 
Chapter 2 


Chapter 3 


Chapter 4 


Chapter 5 


Chapter 6 


Chapter 7 


Chapter 8 


Chapter 9 


Chapter 10 


Chapter 11 


INTRODUCTION 

Describes what Plink86p/us is and how it works. 
INSTALLATION 

Describes Plink86p/us installation procedures. 
COMMAND FORMATS 

Introduces input formats for Plink86p/us com- 
mands. 

OPERATION 

Describes basic PlinkB6p/us operation and com- 
mands. 

OVERLAYS 

Describes how to structure memory overlays. 


SYMBOLS 

Shows how Plink86p/us handles symbols and cre- 

ates symbol tables for symbolic debugging. 

REPORTS 

Describes how to use the Plink86p/us report gen- 

erator to produce linkage output listings. 

EXAMPLES 

Provides useful Plink86p/us examples for linking 

programs with several popular compilers. 

COMMAND REFERENCE 

Provides a comprehensive reference of Plink86p/us 

commands, statements and utility programs. 

ERROR MESSAGES А 

Lists messages generated by Plink86p/us during 

execution and their probable cause. 

PLIB86 LIBRARY MANAGER 4 

Describes how to use the Plib86 library manag 
ipulate object file 

ment program to create and manipu 

libraries. 


iii 
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Appendix А LINKAGE EDITOR CONCEPTS 
Describes what linkage editors do and why they are 
often required for microcomputer program devel- 
opment. 

Appendix B INTEL 8086 CONCEPTS 
Describes Intel 8086 addressing mechanisms that 
are important to the linkage edit process. 

Appendix C OVERLAY LOADER 
Provides technical information about the 
Plink86p/us overlay loader. 

Appendix D DEBUGGING TIPS 
Shows how to use Plink86p/us memory maps for 
debugging. 

Appendix E ASSEMBLER TIPS 
Describes addressing considerations for linking as- 
sembler programs with Plink86p/us. 

Appendix F DISTRIBUTION DISK CONTENTS 
Describes the files on the Plink86p/us distribution 
disk. 

Appendix G COMPILERS SUPPORTED 
Lists compilers that are known to work with 
Plink86p/us. 

Appendix H TROUBLESHOOTING AND PROBLEM REPORTING 
Describes Plink86p/us troubleshooting and problem 
reporting procedures. 

Appendix I Plink86p/us VERSION NOTES 


Summarizes new features and other enhance- 
ments contained in Version 2.2. 


There Is also a glossary, an index and a command reference 
card. 
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Tips for Linkage Editor Beginners 


If you are using a linkage editor for the first time, refer first to 


Appendix A, “Linkage Editor Concepts” and Appendix B, “Intel 
8086 Concepts” for background information about linking pro- 
grams. Then read the introductory chapters to learn how | 
Plink86p/us works before you attempt to install and use the | 
product. f 


Tips for Plink86p/us Beginners 


If you are experienced with linkage editors but are using 
PlinkB6p/us for the first time, review the introductory chapters to 
familiarize yourself with Plink86p/us features not found in other 
linkage editors. Refer also to Chapter 8, “Plink86p/us Examples” 
for sample code that illustrates how Plink86p/us statements are 
used to link files and manage the linkage process. 


Tips for Experienced Plink86p/us Users 


If you are an experienced Plink86p/us user, note that Version 2.2 
enhancements allow you to cache overlays in extended or ex- 
panded memory and to enable automatic overlay reloading for 
selected symbols only. Refer to Appendix I, "Plink86p/us Ver- 
sion Notes" for a summary of new features and other program 
modifications contained in Version 2.2. 


———— — 


Tips for Plink86 Users Upgrading to Plink86p/us 


Plink86p/us provides many new features and enhancements not 
found in earlier Plink86 products, including object file merging, 
overlay caching, automatic preloading and reloading of overlays, 
and automatic allocation of library modules. There are also some 
subtle differences in the way Plink86p/us functions that you need 
to be aware of. Refer to Appendix I, "Plink86p/us Version 
Notes" for a summary of how Plink86p/us 2.2 differs from earlier 
Plink86 1.4x products. 


Customer Support р Ун, 


Comments on this publication and Plink86p/us should be sent to: 


Phoenix Technologies Ltd. 
і =) \ 320 Norwood Park South | 
| Norwood, MA 02062 ! 


j Technical support is available by calling the following telephone 
number: | 
A (617) 769-8310 | | 


For inquiries about other products from Phoenix Technologies |! 
Ltd., please call: | 


| 
T | 1-800-344-7200 
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CHAPTER 1 - INTRODUCTION 


) 
Overview 
Oa ——M  ''—————— a Ma 
m— LCEILCEERCIAZ OO OIERENISIIIC ILIO EV a SR NNNM 
“> This chapter describes what Plink86p/us is and how it works. 
Basic Plink86p/us features and functions are introduced here. 
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What is Plink86p/us 


Plink86p/us 
e is a program linkage editor and overlay management 
software system for the Intel 8086 family of micro- 
processors. 


e is executable under Version 2.1 (or newer) of the 
MS-DOS (and PC DOS) operating system. 


e is compatible with the output generated by most popular 
compilers that produce object files conforming to the Intel 
or Microsoft format standards for 8086 processors. 


Compiler Support 


Refer to Appendix G, "Compilers Supported" for a current listing 
of compilers that are known to work with Plink86p/us. Refer also 
to the READ.ME file on the Plink86p/us distribution disk for 
information about new compiler versions supported since publica- 
tion of this manual. 


PlinkB6plus may work with a compiler not listed here, but there is 
no guarantee. New compiler products are usually similar to 
previous versions, but there may be subtle differences. Consult 
your software distributor or contact Phoenix Technologies Ltd. for 
information about using compilers not listed in this manual. 


The Phoenix Technologies Ltd. newsletter, Pfacts, also contains 
tips about using specific compiler versions as problems and 
solutions are discovered by our technical support staff. Return 
your completed registration card and the newsletter will be mailed 
to you. 
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What Plink86p/us Does a 
Plink86p/us links compiled program and library object files 
together in an output file that is executable by the operating 


1 system. К also creates memory maps and symbol tables that aid 
in program debugging. 


Typically, Plink86p/us is used with programs that are organized 
into logical modules that can be individually compiled and main- 
ү” tained. As shown in Figure 1.1, Plink86p/us links these modules 
together in a single program file that can be executed by the 
г operating system. 


Plink86p/us provides a mechanism for software engineers to 
create and manage programs that are larger than a target 

4 computer's available memory. A program's total memory 
requirement is reduced because modules can share memory 
locations and overlay each other during execution. 


Program Library PLINK86.EXE Executable 


; 2 Y x о SNN 
Object Object Files { 
Files Files | 
Figure 1.1 Linking a program with Plink86p/us E 


nd 
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How Plink86p/us Works 
ЕНЕР ЫЫЫ н ——————— 


Command statements supply Plink86p/us with files to link and 
provide instructions about how to link them. Some statements 
also manipulate how the program operates under certain circum- 
stances or with certain compilers. 


Plink86p/us works intuitively whenever possible. For example, it 
creates an output file or program section automatically if one is 
needed but wasn't specified in the statement input. Similarly, file 
types are assumed if not specified in the statement input. 


When overlays are used, an overlay manager is incorporated by 
Plink86p/us in the executable file to automatically swap the 
overlay modules between disk and memory without requiring calls 
| from the source program. Up to 4,096 tree-structured overlays 
can be created without modifying the source program modules. 


Plink86p/us uses all available memory to hold I/O buffers and the 
description of the program being linked. Up to 32,767 program 
description objects (symbols, segments, groups, etc.) can be 
defined for the linked program. 


Program descriptions are automatically paged to disk in a work 
file if there is not enough free memory. This allows Plink86p/us to 
link just about. any program regardless of size. The work file is 
automatically deleted when the linkage edit is complete. 


These and other Plink86p/us features create an environment 
where very large and complex programs can be made to run 
efficiently despite apparent memory constraints. 
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Plink86p/us ‘‘Two-Pass” Linking 

Ee rs — саанан 

€——À——— SÉ SRÜ 
As illustrated in Figure 1.2, PlinkB6p/us is a two-pass linkage 
editor where each input file is read twice: 


e The first pass determines which modules to load and allo- 
cates segment addresses. 


w e The second pass creates the output file. 


This method takes more time than a one-pass editor, but it | 

ü provides greater flexibility for assigning memory addresses (i.e., 
complete information about all program modules is available 
before the output file is created). 


Determines the Plink86p/us Creates the 
modules to load Executable 
and allocates File 
segment 

addresses 


Figure 1.2 "Two-Pass Linking" 
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Overlay Management 
SS —— MÁS ÀÀ 


Overlays reduce the program's total run-time memory require- 
ment. An application program that is larger than the total avail- 
able memory can be made to execute with overlays because only 
those portions of the program that are required for the current 
function are resident in memory during program execution. 


Overlays are simply sections of the program that share the same 
memory area. One overlay section overwrites another in the 
same memory space when each is required by the application 
program during execution. The Рііпк86р/иѕ overlay loader loads 
these overlays automatically. 


The overlay structure is set up using Plink86p/us input state- 

| ments, SO source code does not have to be modified. The goal in 
overlay structure design is to set up overlays containing function- 
ally isolated portions of the program that will each execute 
independent of other portions. 


As many as 4,095 hierarchical overlays can be stacked as many 
as 32 levels deep. Independent overlay areas that have their own 
hierarchical overlay structure can also be defined. This tree-like 
structure for overlays is similar to the DOS directory structure. 


A disadvantage with overlays is the extra time it takes to load 
them from disk during program execution. Plink86p/us has a 
memory cache feature that can store the overlays in a reserved 
portion of memory when the program is executed. If memory is 
not available for the cache, overlays are loaded from disk each 
time instead. 


The memory cache can also be configured for extended or 
expanded memory if those memory types are available. This 
allows you to configure programs for a small-memory PC-type 
computer that will automatically execute faster on a larger- 
memory PC-AT-type computer, for example. 
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User Interface 


User Interfaco - 1777, ere 
————————Á—— BÀ 


The PlinkB6p/us user interface can be simple or caer 
depending on your skills and the way you want to use tne 
program. 


Plink86p/us statement input can be entered in three different 
ways: 


e interactively in response to program prompts. 


© Included in the command line when Plink86p/us is exe- 
cuted. 


e Inserted from a separate disk file that is identified in the 
command line. 


Placing input statements in a disk file avoids the need for typing in 
a list of commands each time the program is linked. This is how 
Plink86p/lus is typically used when complicated programs are 
being created. 


Instructions for the linkage editor are input using Plink86p/us 
statement commands. Each statement consists of a key word 
followed by optional arguments. The key words can be abbrevi- 
ated by excluding trailing characters. The abbreviation must be 
unique among the entire group of key words. 


Command line input is free format. Multiple statements can be 
placed on one line, or statements can be indented for readability. 


For example: 


OUTPUT TEST.EXE FILE F1, F2, F3 LIBRARY L1, L2 


or 

OUTPUT TEST.EXE 
FILE F1, F2, F3 
LIBRARY L1, L2 


Input Statements 


Plink86p/us input statements include the following: 


STATEMENT PURPOSE 


bOO a ee el 

ALLOCATE Automatically allocates library modules 
to the overlay structure as required. 

ALWAYS Forces use of the symbol vector 
address for references to a 
specified symbol. 

BATCH Causes Plink86 p/us to terminate if it 
cannot find a requested file. 

BEGINAREA Creates an overlay area starting at 
the current memory allocation 
address. 

CACHE Creates an overlay cache in available 
memory or in extended or expanded 
memory. 

CLASS Moves segments in a class to the 
current section. 


COMPATIBLE 


Changes the comment marker from 
ЯҒ” to 4%” for compatibility with earlier 
generated versions of link files. 


Identifies each overlay at the 
console as it is loaded during 
program execution. 


Resolves external symbol references 
by assigning a value if the symbol 
is not defined by any module in the 


DSALLOC Changes the address of the group 
DGROUP to the size of the group 
minus 10000H. 

ENDAREA Identifies the end of an overlay 
area. 


FILE Defines object files for linkage input. Í 


CONTINUED 
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nput Statements, Continued 


Forces DOS to use its own I/O buffers 
by limiting the size of the I/O oper- 
ations Plink86p/us will perform. 


Specifies the maximum memory space 
to allocate beyond the memory 

required to load the program, overlays 
and data areas. 


Assigns all overlayable segments from 
the specified modules to the current 
section. 


NEVER Forces the use of the real address 
and never the symbol vector address 
for references to specified symbols. 

NOBELL Suppresses beeps that sound when 
PlinkB6p/us messages are displayed. 


Input Statements, Continued 
—————_ Ара] 


STATEMENT PURPOSE 
(ee eS ee 

NODEFLIB Suppresses automatic library search 
requests. 

NOLOCALS Eliminates all local symbols and line 
numbers from the symbol table. 

NOPUBLICS Specifies symbols that are not 
globally accessible after an object 
file merge. 


NOSYMGROUP Changes how addresses are 
computed for certain external symbol 
references in object files. 


NOTYPCHECK 


Disables TYPDEF record processing 
as required for linking large programs 
compiled with the Intel PL/M or 
Microtech Research Professional 
Pascal compilers. 


NOVECTOR 


NWIDTH 


OUTPUT 
OVERLAY 


PRELOAD 
PUBLIC 


Page 1-10 Plink86plus User Manual 


Effectively sets the NEVER statement 
for all variables in specified files only, 
prohibiting PlinkB6 p/us from vectoring 
any of those symbols. 


Sets the column width for symbol 
names and other identifiers on map 
reports. 


Creates a .EXE file to hold the linked 
program or a .OBJ file to hold merged 
object files. 


Specifies segment classes that can 
remain In the overlay structure. 


Loads a specified overlay section into 
memory before passing control to the 
user program. 


Suppresses symbol names in a merged 
object file, except for those specified 
by this command. 


CONTINUED 
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nput Statements, Continued 


STATEMENT PURPOSE 


RELOAD 


Reloads overwritten overlays 
automatically as required by the 
program. 


SEARCH Defines libraries for linkage input and 
searches them repeatedly for un- 
defined symbol definitions. 


Creates a program section that is 
loaded from disk as a separate unit 

or (SECTION INTO) copies an overlay 
file into a separate disk file. 


STACK Changes .EXE file header stack size. 
SYMGROUP Selects the way the Intel 8086 object 
format is handled by Plink86p/us. 
SYMTABLE Generates a symbol table for use with 
the Pfix86plus symbolic debugger. 
TINY Strips debugging information from 
merged object files. 


Enables automatic overlay reloading 
for selected symbols only. 


SECTION 


Translates all symbol names and 
identifiers to upper case. 


VERBOSE Displays a status line at the console. 
WIDTH Sets page width for map reports 
(default: 80). 


WORKFILE Specifies a file name other than the 
default PLINK86.WRK and optionally 
a path for the PlinkB6p/us temporary 
work file. 


These input statements are described as PlinkB6p/us func- 
tions are introduced in the next several chapters. e E 
Chapter 9, Command Reference for a detailed alphabetic 


statement reference. 


Debugging Tools 


Plink86p/us provides program tools that aid in debugging. These 
tools include symbol tables, memory maps, utility programs and 
program status messages. 


PlinkB6p/us can generate a symbol table that provides information 
about the names and addresses of symbols in the program. The 
symbol table is appended to the output file that is created to hold 
the linked program. A utility program can delete the symbol table 
later without relinking the program. 


Symbol tables provide input for the Pfix86p/us symbolic debug- 
ging program. With Pfix86p/us, you can refer to your program's 
procedures and public symbols by name instead of by absolute 
address. Also, Pfix86p/us adds the symbols to its display win- 
dows, making the assembly language code and hex data 
displayed there more readable. 


The symbol table also provides Pfix86p/us with information about 
overlays, enabling the debugger to handle tasks like setting 
break-points in overlays not currently in memory. 


Memory map reports can aid in the debugging process. These 
reports describe the output of the linkage edit and can be 
selected in several different reporting formats. 


Plink86p/us can also display the program's current status during 
the linkage edit and a debug mode can issue a message that 


identifies each overlay as it is loaded during the actual program 
execution. 
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Utility Programs ЕЕЕ 
2 А і һө 
Plink86p/us includes several utility programs to assist with t 


Process of managing the linkage edit. These utility programs апе 
contained in .EXE files on the Plink86p/us distribution disk. 


Plink86p/us utility programs are as follows: 


PROGRAM PURPOSE 
ee el 


CHECKSUM.EXE Validates the checksum of any .EXE 
file. This is useful for determining if 
executable files have been damaged. 

COMPARE.EXE Performs a byte-by-byte comparison 
of two files and reports the dif- 
ferences. This is useful if CHECKSUM 
indicates a file has been smashed 
somehow. 

DUMP.EXE Dumps the contents of a file in a 
readable format to the console or 
disk. This is useful for viewing ex- 
ecutable files and object files in a 
readable format. 

PLIB86.EXE Creates and manipulates object library 
files. Libraries are a common mech- 
anism for organizing object files for 
the linkage editor. 

SYMTABLE.EXE Prints or deletes a symbol table. This 
is useful for debugging and also for 
deleting the symbol table from a 
finished program without relinking. 
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Plink86p/us Terminology 
ШИШЕ асы ee | 


The following terms are used throughout this manual: 


TERM (тем __ | юсю | 
ГЕК ЫИ ДЫ 02-272. ——— File A linkage editor output file the 
operating system can execute. 


Object File Compiler output file used as an input 
file by the linkage editor, also called 
a relocatable file because it contains 
code that can be modified by the 
linkage editor to execute at any 
memory address. 

Module A module is a unit of code in source or 
object form. A compiler or assembler 


typically takes a single source module 


as input and creates a single object 
module contained in a single object file 
Public 
Segments 


as output. 


A section is a unit of executable code 
for handling by the overlay manager. A 
section is usually an overlay, a portion 
of the executable file that is loaded 
into memory as a single unit. 


A piece of code or data that is manipu- 
lated by the linkage editor as an 
indivisible unit. 


Segments that can be combined with 
other segments of the same segment 
and class name to occupy adjacent 

locations in memory. 


Private Segments that cannot be combined 
with other segments to occupy 


adjacent memory locations. 


Segments 
A section that shares all or part of 
its memory allocation with other sec- 


Overlay 
tions. 


CONTINUED 
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link86p/us Terminology, Continued 


DESCRIPTION 


An address classification that defines 
a collection of segments (64kB 
maximum) to be accessed by the 
same segment register. 


A classification assigned by the 
compiler to identify and order a 
collection of segments. 


Library A relocatable file containing modules 
that are individually available to the 
linkage editor. 


The assigned name for a value that 
is a constant (absolute symbol) or 

the address of a program component 
(relative symbol). 


A symbol whose relative address is 
designated by the compiler to be 

available for modules other than the 
module that defines it. 


A symbol that is not defined in a 
module that references it. The 

linkage editor fixes these references 
when their values become known. 


Special segments created by Fortran 
and other compilers that allow 

modules to share data areas by over- 
lapping like-named common blocks 
defined by other modules. 


External 
Symbol 


Common 
Block 


L 
n 
, 
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Tips for Beginners 


OO eee 
Plink86p/us is a software tool whose utility grows with your 
understanding of its processes. For best results, adhere to the 
following guidelines when using Plink86p/us initially: 


e Start by performing simple links and then build your skills 
gradually. 


e |f your program will fit into memory, get it working without 
overlays first. 


ө Add overlays one at a time, building your overlay struc- 
ture in stages so you will always know when a new bug 
has been introduced. 


ө |f your program is very large, like a mainframe program 
being ported down, try stubbing out parts of it to make a 
non-overlaid version fit. Then build the overlay structure 
as described above. 


e Do not mix and match object files from different compil- 
ers. They are probably not compatible and unpredictable 
results can occur. 


ө Initially, use a single high-level language exclusively and 
don't mix and match code. 


e (|f possible, do not add assembly language until the first 
test version of your program is running. 
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Overview 

i , ES 
— ŘE ИНИСИ 
9 This chapter describes how to perform initial Plink86p/us system 
check-out and installation. 


| Chapter Contents 
(GopyabrotectionlNNOLt o Жз: reise ren en nea 
Installing; Plink86píuS s. x otis cole: o cee etn ae лал 
4 Step 1: Distribution Disk Backup 
Step 2Test-Procedures т Ж 777722255222. 
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Copy Protection Note 


The Plink86p/us distribution disk is not copy-protected. This is 
because PlinkB6p/us is viewed as a systems software tool that 
must be accessible at all times without requiring insertion of a 
particular diskette. 


Make as many copies as you want. Recall, however, that your 
software distribution agreement specifies that each Рііпк86р/иѕ 
package is for use on a single machine only. 


This means copies you make are for your computer only. It is 
illegal and unethical to distribute them for use on other machines. 
Respect this, please. Phoenix Technologies Ltd. is prepared to 
use any legal remedy to enforce its distribution agreements. 


Installing Plink86p/us 


The Plink86p/us installation requires two separate steps: 


1. Copy the Plink86p/us distribution disk to a diskette or hard 
disk. 


2. Use your new copy of the program to execute a series of 
tests that determine if the software is хото properly on 
your computer. 


Read the pages that follow for detailed installation information. 
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Step 1: Distribution Disk Backup 


Plink86p/us writes data to the disk and cannot be executed on the 


distribution disk. This disk is write-protected to insure that its 
contents cannot be accidentally altered. Contents of the distribu- 
tion disk can be found in Appendix F. 


You must create an archival copy of the Plink86p/us distribution 
disk on another diskette or on a hard disk before attempting to 
install and use the program: 


Copy the Plink86p/us distribution disk to a 
formatted diskette or to a hard disk using 
the DOS COPY *.* command. 


COPY *.* «drive id» 


Copy the PLTEST, UTILS, and OVERLAY 
subdirectories from the distribution disk 
to the formatted diskette or hard disk: 


CD\PLTEST 
COPY *.* <drive id> 


CD UTILS 
COPY *.* «drive id» 


CD OVERLAY 
COPY *.* «drive id» 


Store the PlinkB6p/us distribution disk in a 
safe place and use it only for making 
additional copies when required. 


Use your new copy of PlinkB6p/us to 
execute the test procedure and for normal 
operation. 


Step 2: Test Procedures 


The Plink86p/us test procedure provides a quick test of the 
software to make sure it is working properly on your computer. 


Execute the following: 


ACTION 


Execute the CHECKSUM utility program on the 
Plink86p/us program file by typing 


CHECKSUM PLINK86.EXE 


The program should reply: 
CHECKSUM OK 


e If the 'OK' message is issued, proceed to 
Step 2B. 


e If the ‘OK’ message is not issued, run 
CHECKSUM again. If CHECKSUM consis- 
tently fails, you may have a bad copy of 
Plink86p/us. Your copy operation may 
have a bad copy of the program. To 
identify the problem, run 
CHECKSUM PLINK86.EXE on the 
distribution disk. 


e If CHECKSUM executes correctly, 
copy the distribution disk again and 
retry the operation. 


e If CHECKSUM fails on the distribution 
disk, request a replacement copy 
from your software distributor. 


CONTINUED 
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Step 2: Test Procedures, Continued 


(a 


Link the PLTEST test program by typing 
PLINK86 @PLTEST 
The program should execute for a short 
time and reply: 
PLTEST (12K) 


Execute the PLTEST program by typing 
PLTEST 
and then press <ENTER>. 


The program should reply: 
PLTEST OK 


This means the linked program has 
successfully executed. 


If these tests complete successfully, you 


are ready to start using Plink86p/us. 


If the tests fail to execute as described 


here, then something about your operating 


environment is not compatible with your 


copy of Plink86p/us. Consult your software 


distributor to remedy this problem. 


Chapter 2 - installation 


Page 2-5 


"| 
| | CHAPTER 3 - COMMAND FORMATS 
$ Overview 
L. {| |е һо ee ee а 77-4] 


This chapter describes how to initiate Рііпк86р/иѕ program execu- 
tion, including command syntax and input formats. 
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Program Initiation 


Plink86plus execution is initiated with the command 'PLINK86'. 
There are several different ways to use this command: 


ә interactively, where Plink86p/us prompts for entry of input 
arguments. 


e With input arguments included in the Plink86p/us com- 
mand line string. 


e With input arguments in a separate disk file that is 
identified in the Plink86p/us command line string. 


Each of these methods is described in this chapter. 


Interactive Input 


Plink86p/us can be used interactively with the format: 
PLINK86 «cr» 
«cr» means to press the «RETURN» or «ENTER» key. 


In interactive. mode, PlinkB6p/us executes and then prompts for 
entry of input statements. The displayed prompt is =>. Any 
number of lines can be entered. Standard MS-DOS line editing 
features are available during entry. 


Use «ENTER» or «RETURN» to begin a new line. Each line is 
checked for syntax and then stored until all lines have been 
entered. Interactive input is ended with a semi-colon ' ; ' 
character. The semi-colon is only required when terminating 
input in interactive mode. It is not required when statement input 
Is from the command line or from a disk file. 
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| Interactive Input, Continued 
Interactive Input Example , | 
Suppose you have a complete assembler program consisting of 


SS the source file TEST.ASM, which is assembled to produce the file 
| TEST.OBJ: 
{ STEP ACTION 


Execute PlinkB6p/us by typing 
РГІМК86 
and then press <ЕМТЕН>. 


FILE TEST.OBJ; 


This links the file TEST.OBJ and produces | 
the output file TEST.EXE. 


4 At the prompt =>, type 


= 27 Command Line Input 
i Y 


You can bypass interactive mode and include the input argu- 
ments as part of the command line with the format: 


| 
PLINK86 [statements] «cr» | | 
«cr» means to press the «RETURN?» or «ENTER?» key. | 


With this format, Plink86p/us executes all statements entered on 8 
the command line and returns the DOS prompt when it has 
finished. 
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Command Line Input, Continued 


Command Line Input Example 
in this example, PlinkB6p/us is executed with the FILE statement 
and the input file TEST.OBJ included on the command line. 


ACTION 


Execute PlinkB6p/us with statement input in 
the command line by typing: 


PLINK86 FILE TEST.OBJ 


or 
PLINK86 FI TEST 


TEST.OBJ is the object file to link. If no 
file type is specified, .OBJ is assumed. 


‘Fl’ is an abbreviation for the key word 
'FILE' in the statement. Each key word can 
be abbreviated in the command line by 
leaving off characters on the right, so long 
as the abbreviation is unique among the 
group of key words. 


Note: At least one FILE statement is 
required in the command input to 
rovide the names of the files to 
ink. All modules appearing in the 
files are included in the output 
program. 
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Input From Disk Files 
EEE 


A disk file containing all or part of the statement input can be 
inserted in the Plink86p/us command line. The file name to input 
is preceded by the at '(?' character. The format for including disk 
files in the command line is: 


Plink86 @<file name» 


“а instructs Plink86p/us to insert the contents of the specified file 
at the current point in the input stream. “0” files have the same 
format as any other Plink86p/us input. A file type of .LNK is 
assumed unless otherwise specified. 


Plink86p/us disk file input is typically used when complicated 
programs are being created. Complex overlay structures set up 
for common routines can be stored in a separate file and then 
used interchangeably with different programs. 


қа” file input can appear at any point іп the input stream and can 
be freely mixed with other statement input. '(2' files can also be 
nested yp to three levels deep. That is, the first ‘@’ file can 
contain a reference to a second ‘@” file, which can contain а 
reference to a third. 


Regular input can also be mixed with ‘@’ files. 


For example, PLINK86 (TEST VERBOSE links the program as 
above and also invokes the VERBOSE function. This input method 
is convenient for inserting additional options specifically for the 
current linkage edit. 


Disk File Input Example 


In this example, Plink86p/us is executed with the FILE statement 
and the input file TEST.OBJ inserted from a disk file. A second 
level of input is also inserted. 
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Input From Disk Files, Continued 


STEP ACTION 


Use your text editor to create a file named 
TEST.LNK containing the following: 


OUTPUT  TEST.EXE 
FILE TEST.OBJ @TEST2.LNK 


е Execute PlinkB6p/us with statement input 
inserted from the disk file TEST.LNK by 
typing 


PLINK86 @TEST.LNK 


9 Press the «ENTER» key. 


Result: 


This instructs Plink86 р/иѕ to insert the 
contents of the disk file TEST.LNK in the 
input stream. 


The reference to @TEST2.LNK in the file 
TEST.LNK instructs the program to insert 
the contents of a second .LNK file at that 
point in the input. TEST2.LNK might 
include the following: 


LIB MATHLIB.LIB MAP = TEST 
. The result of using '(' to insert input from 


TEST.LNK and TEST2.LNK is the same as if 
you had typed: 


PLINK86 OUTPUT TEST.EXE 
FILE TEST.OBJ 
LIBRARY MATHLIB.LIB 
MAP = TEST 


In this example, the file TEST.EXE is pro- 
duced as before, but now the library 
MATHLIB.LIB is searched for any required 
modules and a memory map is produced on 
disk in the file TEST.MAP 


7 @ 
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Output Format 


Plink86p/us links the input files in a file that can be executed by 
the operating system. This output file defaults to file type .EXE 
unless otherwise specified. 


In the previous examples, Plink86p/us would link the program and 
display the message: 


TEST.EXE (5K) 


This means the output program TEST.EXE was created success- 
fully. if an error occurs, Plink86p/us displays an error message 
instead of this message. 


The displayed memory requirement is not the size of the disk file 
generated by Plink86p/us. Instead, it is the amount of memory 
required by the operating system before the linked program can 
be loaded for execution. This number is rounded upward to the 
nearest 'kB' (1024 bytes). 


By default, PlinkB6p/us names the output file by using the name of 
the first input file and appending the file type .EXE. 


The OUTPUT statement can name the file explicitly. In these 
examples, the linkage output file could be named MYTEST.EXE 
with the command: 


PLINK86 OUTPUT MYTEST FILE TEST.OBJ 
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16-Bit Radix Values 

I — Ыы 
16-bit values can be expressed numerically in several different 
bases, including hexadecimal, decimal, octal and binary. An 
optional radix character immediately following the number indi- 
cates which base you are using. 


When the radix character is omitted 
e Hexadecimal is assumed when the value will be inter- 


preted as an address or constant. 
e Decimal is assumed 


e when the value specifies a count, such as the number 
of characters on a printer line, or - 


e when the value is a percentage for cache memory or 
the number of kbytes for a cache (100k). 


Numerical bases and radix characters are as follows: 


ex O-OFFFFH 
Decimal 0-65635 
Octal 0-1777770 


Binary 16 Digits 


an octal number 

a hex number 
Жж. 5 a decimal number 

11 binary 

11B hex 


Page 3-8 Plink86p/us User Manual 


Identifiers 


| An identifier is the name of some object, such as a symbol, 
| module or segment. A simple identifier is a sequence of up to 


255 printable ASCII characters containing no spaces and none of 
=) the following: 
AA 


^2:«»1,1'£& * -:Q N 


The first character must be a non-blank and may not be a digit 
from O - 9. 


You can override these restrictions with the escape character 
* ^ ', The first character following the escape character is treated 
as a normal identifier character, such as ^@ to include ''. The 
Al exception is the first character, which must still be a non-blank. 


To include the escape character as an actual character in the 
identifier, enter two escape characters ‘ ^^ '. 


Plink86p/us accepts identifiers in either upper or lower case. You 

can override this with the LOWERCASE statement to force all 
AN) identifiers and symbol names to lower case, or the UPPERCASE 
statement to force them to upper case. 


-<2 


Identifiers appearing in object files are significant to 255 charac- 
ters for symbol names. 


VALID 
INVALID IDENTIFIERS IDENTIFIERS 


34ABC (starts with a number) 
NIM A (contains a space) | ММА | | 


PROG#1 (‘#’ starts a comment) PROG^#1 


T md 
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Disk File Names 


а EL | 
File naming formats for Plink86p/us are the same as the formats 
used by the MS-DOS operating system: 


[device:] [path] FILENAME[.type] 


Optional format parameters are shown here in brackets. File 
names can be up to eight characters, file type up to three 
characters. For example, TESTFILE and TESTFILE.EXE are valid 
file names, TESTFILES.EXEC is not. The name string can be up to 
64 characters long. The following characters are valid for file 
names and file types: 


A-Z0-9$&()-{}-'! 


An invalid character in a file name terminates the name. How- 
ever, the escape character ' ^ ' can put any character except 
spaces in a file name. 


[device:] and [path] are optionally prepended to the file name to 
specify the file's disk and directory. This is only required when 
the file is not located in the current disk and directory. [device:] 
specifies the drive and [path] specifies the directory where the 
file is located. 


For example, if TESTFILE is in a directory named TESTDIR in Drive 
B, it can be referenced: 


e from Drive A as B:NTESTDIRNTESTFILE 
ө from Drive B directory TESTDIR as TESTFILE 


e from the root of Drive B as TESTDIRNTESTFILE 
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Disk File Names, Continued 
e ee e e e e a ee e E 7 9 
— ee ee 
The following file types are recognized or generated by 
AE PlinkB6p/us for specific types of files: 


um. DESCRIPTION 


Executable files 
Object file 


Overlay loader file 
Library file 

“а” Link file 
Temporary work file 
Memory map file 


ЕТ 


Statement Format 
— eS ee XA GEM 
All Plink86p/us input is free format. Input is a list of statements: 


E ғу 
Y [statement] ... [statement] 


Blank lines are ignored. Each statement can extend to any 
number of lines. Comments can be included with input from any 


| 
source by using a pound sign ‘#’. When ‘#’ is encountered, all 
remaining characters on the line are ignored. 
Each statement consists of a key word. Many key words are 
optionally followed by arguments. 


ы: For example: OUTPUT TEST.EXE 
M FILE A.OBJ, B.OBJ, C.OBJ 


OUTPUT is a key word and TEST.EXE is its argument. FILE is a 
| А 4 key word апа А.ОВЈ, В.ОВЈ and С.ОВЈ аге its arguments. This 


p» example links object files A.OBJ, B.OBJ and C.OBJ in an output 
|. file TEST.EXE. 
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Statement Format, Continued 


Key words can be abbreviated by excluding trailing characters. 
The abbreviation must be unique among the entire group of key 
words. 


For example: OUT TEST.EXE 
Fl A.OBJ, B.OBJ, C.OBJ 


This example is the same as the previous example. The key 
words OUTPUT and FILE are abbreviated here as OUT and Fl . 


The file type is assumed by Plink86p/us for many statement 
arguments if not specified. 


For example: OUT TEST 
FIA, B, C 


The file created here by the OUTPUT statement is assumed to be 
an .EXE file. The input files specified with the FILE statement are 
assumed to be .OBJ files. 
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Verification and Errors 

R E E S TR TED 

— SEE eee 
When a program is successfully linked, the program name is 
displayed on the console with its run-time memory requirement. 


- The displayed memory requirement is not the size of the disk file 
generated by Plink86p/us. Instead, it is the amount of memory 
required by the operating system before the linked program can 
be loaded for execution. 


nU This number is rounded upward to the nearest ‘kB’ (1024 bytes). 

їй It is an approximation that does not account for the possibility of 
the program attempting to allocate more memory space to itself 
at run time. 


t4 If a syntax error is encountered in the input line during entry, the 

| current line is displayed with two question marks inserted after 
the point where the error was detected, and the program termi- 
nates. 


Plink86p/us displays warning messages when potential problems 

(such as a group not residing іп а single 64КВ segment) are 
^ encountered while processing the input. These messages are 
] 1 numbered and include a problem description. 


| Fatal errors (such as a full disk) can occur during processing. 
Plink86p/us displays an error message explaining why it is returr. 
ing to the operating system. Recovery options are only for "Fil 
not found", which is not a fatal error. Error messages аг. 
numbered and include a brief description of the problem. 


| Refer to Chapter 10, “Error and Warning Messages” for more 
| information about Plink86p/us errors. 


| 
| 
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CHAPTER 4 - OPERATION 


Overview 


This chapter describes Plink86p/us operation and introduces 
statements that link your programs and manipulate the way 
Plink86p/us performs the linkage edit. Utility programs for use with 
Plink86p/us are also described here. 
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Chapter Contents 
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Object File Formats 
CEER 


Object files (filename.OBJ) contain the compiler output. They are 
an intermediate form of the generated code containing informa- 


~ T tion required by the linkage editor. 
{ d) Object files are used as input to the linkage editor, which 
transforms them into executable machine language and links 
) them with other input files in the output file. 
к Plink86p/us accepts object files in either the Intel format or the 
Microsoft format: 


ө The Intel format is described in the Intel document “8086 
Relocatable Object Module Formats (#121748-001).” 


mef е The Microsoft format is derived from the Intel format but 
contains many modifications. 


Plink86p/us and its utility programs handle both the Inte! and 
Microsoft formats automatically. Refer to Appendix G, 
"Compilers Supported" for more information about compiler 


^ compatibility. 
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Define Input Object Files 


Object files are normally input to the Plink86p/us linkage edit with 
the FILE statement. At least one FILE statement must appear in 
the input to define the files to link. 


STATEMENT DESCRIPTION 


The FILE statement defines the object 
files for PlinkB6p/us to link. The file type 
.ОВЈ is assumed for these input files if 
none is specified. All modules contained 
in the listed object files are included in 
the output program. 


Example: To link the files TEST.OBJ 
and F2.OBJ іп an output file named 
TEST.EXE: 

FILE TEST.OBJ, F2.0BJ 

or 


FILE TEST, F2 


The FILE statement is normally used for linking the .OBJ files 
only. Library files are normally linked in with the LIBRARY or 
SEARCH statements. These statements search the file and 
include only the required modules. 


Object files may be included in LIBRARY or SEARCH statements, 
but they are not loaded until all files listed in the FILE statement 
are loaded. (This is because Plink86p/us processes all files listed 
in FILE statements before files from the LIBRARY or SEARCH 
statements are examined, regardless of the order of statements 
in the command input. This order of processing insures that 
Plink86p/us will know which symbols are still undefined before it 
begins the actual library search.) 
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Define Input Libraries 


Library object files (filename.LIB) are normally input to the 
Plink86p/us linkage edit with the LIBRARY or SEARCH statements. 
All modules contained in the listed files are searched, but only 
modules that are actually required by object files in the FILE 
statement(s) are included in the output program. This is called a 
library search. 


STATEMENT DESCRIPTION 
Sn a | 


LIBRARY The LIBRARY statement defines the 
library object files whose modules are 
available to the linkage edit. The file 
type .LIB is assumed for these input 
files if none is specified. 


Example: To include required 
modules from the library files TEST.LIB 
and F2.LIB as input to the linkage edit: 


LIBRARY TEST.LIB, F2.LIB 
or 


LIB TEST, F2 


The SEARCH statement is the same as 
LIBRARY except that Plink86 plus can 
make multiple passes through the 
specified files if undefined symbols remain 
even after all specified files have been 
read. 


Example: To allow multiple passes in 
TEST.LIB and F2.LIB to find all required 
input modules for input: 


SEARCH TEST.LIB, F2.LIB 
or 


SEARCH TEST, F2 
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Library Search Process 
T 


Modules selected for input from LIBRARY files define symbols 
that are not defined by modules already input to the linkage edit. 
These symbols were declared external by the other modules. This 
library search method reduces the size of the linked program 
because it loads only those library modules that are actually 
needed. 


Library files can also be included in the FILE statement, but every 
module in the library file is linked in with that method, and most 
libraries contain multiple versions of modules. Library files are 
usually included in the FILE statement only when Plib86 was used 
to combine several modules of a program into a library to reduce 
the number of files on disk. 


SEARCH is rarely used, but is quite useful in situations where all 
required modules cannot be pulled from a specified library in one 
pass. This could occur if two libraries are being searched that 
each refer to symbols defined in the other. 


Plink86p/us first loads all files from the FILE statements and then 
makes a first pass through all files from the LIBRARY and 
SEARCH statements to select modules that define symbols that 
are undefined in the input object files. 


If symbols remain undefined, all files from SEARCH statements 
are then searched again one or more times until all symbols are 
defined or until all logical avenues have been pursued to find the 
definitions. 


Note: Embedded library search requests, such as those cre- 
ated by the Microsoft compilers, are treated as SEARCH 
statements. 


Page 4-6 Plink86p/us User Manual 


Define Output Files 
Б a SS н 


Plink86p/us creates an output file (filename.EXE) to hold the 
linked program that is created as the output of the linkage edit. 
This file can then be executed by the operating system. The 
output file replaces any existing file with the same primary name 
and file type on the disk. 


An output file is generated automatically by Plink86p/us during the 
linkage edit. The file name is the primary name from the first input 
file in the FILE statement, with the file type .EXE appended to it. 


Alternatively, a different output file name can be specified with 
the OUTPUT statement. 


STATEMENT DESCRIPTION 


OUTPUT The OUTPUT statement specifies a 
different output file name than what 
Plink86p/us would select. The file type 
defaults to .EXE if not specified. When 
specified, .EXE or .OBJ are allowed. 


== ў OUTPUT is only required when you want 
to specify an output file name other 
than the primary name of the first input 
file or to specify a file type other than 
the default. 


Y 
Example: To link the files TEST.OBJ 
and F2.0BJ in an output file named 
FOO.EXE: 


OUTPUT FOO.EXE FILE TEST.OBJ, F2.0BJ 


| ог 
Н | OUT FOO FILE TEST, F2 


и 
a 


{ 
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If OUTPUT were not specified in this example, Plink86p/us would 
automatically create an output file named TEST.EXE (the primary 
name of the first file listed in the FILE statement). 


Finding the Object Files 
т = — а 2 ыы лл ——— 


If Plink86p/us cannot find a requested object file, it looks in the 
DOS environment for a string named “OBJ” that contains direc- 
tory paths to search. The DOS SET command creates this string. 
The value of the string is assumed to be one or more directory 
path names separated by semi-colons. The format is the same 
as the DOS PATH command. 


These path names are prepended to the object's filename one at 
a time in an effort to find the file. Any drive references are 
stripped from the file name. The path name separator character 
is inserted between the path name and file name. 


SET EXAMPLE: ІР SET OBJ=\OBJECT;\LIBRARY is entered 
before executing Plink86p/us, a search for the file TEST.OBJ 
would include TEST.OBJ, \OBJECT\TEST.OBJ апа then 
NLIBRARYNTEST.OBJ. Do not put spaces around the equal sign in 
the string or Plink86p/us will not be able to find the path names. 


If the requested file cannot be located using the search paths (or 
if the OBJ string does not exist), Plink86p/us prompts for entry of 
a prefix string (e.g., "A:" or “\OBJECT\”) that will be prepended 
to the front of the filename after any existing drive reference is 
stripped out. 


Diskettes may be changed here except when the current disk 
contains open files like OUTPUT or MAP files or the temporary 
work file that is opened if Plink86p/us runs out of memory space. 


Note: The BATCH statement can be inserted in the input to 
terminate Plink86p/us rather than prompt for a prefix 
string. This is useful when Plink86p/us is executing from a 
batch file. 


Page 4-8 PlinkB6plus User Manual 


Input object files can be merged by the OUTPUT statement into a 
single object file that can then be input to another linkage edit. 


B | 
| Merging Object Files 
| 
m 


STATEMENT DESCRIPTION 


* 
| OUTPUT The OUTPUT statement merges object 
] 


— 


He files together. The file type .OBJ must be 
specified for the output file. Plink86 plus 
then merges input object files specified 

in the FILE statement into a single object 
file using the file name supplied by the 
OUTPUT statement. 


Example: To combine the object files 
TEST.OBJ апа F2.OBJ in a file named 
FOO.OBJ: 


OUTPUT FOO.OBJ FILE TEST. OB3J, F2.OBJ 


There are several reasons why object merging is desirable: 


e |f object files not currently under development are 
merged, the linkage edit is faster because there are 
fewer files to open and a smaller amount of linkage infor- 
mation to process. 


e Merged object files provide flexibility for packaging soft- 
ware in the form of object files that can be linked into 
user software. The merged software package is easier to 
link in with the application software, and since there is 
only one file, managing program updates is simplified. 


e Performing an object merge allows all symbol names to 
be removed except those used to communicate with the 

= package. For software packaged in object form, this re- 
ia) duces the possibility of user-defined duplicate symbols 


gu interfering with linkage edit information. 
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Merging Object Files, Continued 


By default, public (i.e, "global") symbols remain public when 
object files are merged. The PUBLIC and NOPUBLICS statements 
override this default for all or selected symbols. 


Debugging information from the compiler is also merged into the 
resulting composite object file. The TINY statement strips this 
information from the merged file. 


STATEMENT | DESCRIPTION 


PUBLIC 
NOPUBLICS 


TINY 


Example of TINY and PUBLICS 


The PUBLIC statement forces all symbols 
that were compiled as public to become 
Static. Exceptions can be specified. 


The NOPUBLICS statement forces 
selected public symbols only to become 
static. 


The TINY statement strips all debugging 
information from the merged file. This 
produces a slightly smaller file. 


In the following example, all public symbols in the merged object 
file FOO.OBJ become static except PROC1 and PROC2 and all 
debugging information is stripped out. 


OUTPUT FOO.OBJ FILE TEST.OBJ, F2.OBJ 


PUBLIC PROC1, PROC2 TINY 
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Merging Object Files, Continued 
| 


Listing Merged Files 


When used during an object merge, the MAP statement lists the 
modules, groups, segments, and variables in the newly created 
object file. Requests for a section list are ignored during the 
object merge. 


"тет 


Variables сап be one of seven types: 


me e EXTERNAL (not defined by the merged file). 
e PUBLIC 
e PRIVATE (previously public, now suppressed). 
- | e PUB ABS (public absolute). 
e PRIV ABS (private absolute). 
e PUB DEF (user-defined public absolute) 


A^ e PRIV DEF (user-defined private absolute) 


User-defined variables are those created by a DEFINE statement 
in the Plink86p/us link file. 
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Section Organization 


PlinkB6p/us creates a new program section automatically when- 
ever a statement like FILE or LIBRARY is encountered that 
requires a section to put things in. The SECTION statement can 
force a new section at any point in the input. 


STATEMENT DESCRIPTION 


SECTION The SECTION statement creates a new 
program section. Module segments 
obtained via FILE, LIBRARY or SEARCH 
statements that appear after a SECTION 
statement are loaded into the section. 
SECTION can also specify an optional 
section name to appear ín memory map 
reports. 


Example: To assign TEST and F2 to 
the first section and F3 and F4 to a 
second section named GLOBAL: 


SECTION FILE TEST, F2 
SECTION = GLOBAL FILE F3, F4 


Note: The first SECTION statement is 
not actually required in this 
example because Рііпк86р/иѕ would 
create a section for TEST and F2 
automatically. 


The second SECTION statement 
is required here for two reasons: 


ө it specifies а new section for ЕЗ 
and F4 and it provides the name 
"GLOBAL" for the new section. 


® The second section is assigned 
a memory location following the 
end of the first section by 
Plink86 p/us. 
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Automatic Segment Ordering 


A simple non-overlaid program consists of a single section 
containing all segments in the standard “canonic” definition of 
segment ordering. Canonic ordering allocates memory to seg- 
ment classes in each section in the same order they appear in 
the input files. Within each class, segments are allocated mem- 
ory in the order the segment names are encountered. 


Plink86pius uses the canonic segment ordering unless it is 
deliberately altered with a statement such as the CLASS state- 
ment. A segment's group has no bearing on the canonic order. 
Segments are linked in the order they are read from FILE, 
LIBRARY or SEARCH statements. 


For example, if the first module linked defines segments as: 


NAME CLASS 
BASE PROG 
DATA DATA 
PROG PROG 
STACK DATA 


The segments are assigned memory in the order BASE, PROG, 
DATA, and STACK. Note that the two segments in class PROG are 
first, followed by those in class DATA. 


When the program contains more than one section (i.e., a 
program with overlays), segments are ordered canonically within 
each section rather than over the entire program. For example, if 
there were two sections with PROG and DATA segments, PROG 
would be first in each and DATA would be second in each. 
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Manual Segment Ordering 
[orn 6s O ee ee a Eee ee ee ЕЕЕ] 


Normally, the FILE, LIBRARY, SEARCH and SECTION statements 
structure the program segments into sections. However, assem- 
bly language programmers and others occasionally need to 
specify segment ordering and arrange segments in a particular 
fashion to get the right things into overlays, to insure that groups 
can be addressed properly and to restore the canonic segment 
ordering. 


PlinkB6p/us provides ordering statements that override the 
canonic segment ordering. These statements are not required for 
normal linkage edit operation and should be used carefully. 


The relative importance of statements for assigning segments to 
sections is as follows: 


Highest Priority CLASS (with segments) 
CLASS (without segments) 
MODULE 
GROUP 

Lowest Priority FILE, LIBRARY, SEARCH 


The CLASS, MODULE and GROUP statements perform the fol- 
lowing segment ordering functions: 


Page 4-14 Plinks6 plus User Мапцај 


Manual Segment Ordering, Continued 
SES eee 


STATEMENT| DESCRIPTION 


CLASS 


The CLASS statement moves some or all 
segments (including private segments) in 
a specified class to the current section. 
CLASS overrides all other specifications 
and changes the program’s canonic 
ordering. 


Note: CLASS was used extensively in 
earlier versions of Plink86p/us to set 

up overlay structures. This is now 

done automatically. 


Example 1: To move all segments in the 
class MEMORY to the current section: 


CLASS MEMORY 


| 
і 
% 
i 
{ 
i 
| 
{ 
i 


CLASS can also move only specified seg- 
ments of a class to the current section. 


Example 2: To move OV1DATA and 
OV2DATA only from the class DATA to 
the current section: 


CLASS DATA (OV1DATA, OV2DATA) 


Classes and segments specified by CLASS 
become part of the canonic segment 
ordering of the program and appear 
before those defined by program modules. 
This is because all input statements are 
processed before the first object file is 
read. As a result, even if CLASS is used 
only to move something from one section 
to another, you must be careful to 

restore the canonic ordering to what it 
should be. 


CONTINUED 
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Manual Segment Ordering, Continued 


STATEMENT} DESCRIPTION 


MODULE The MODULE statement assigns all seg- 
ments from specified modules to the 
current section. MODULE overrides the 
FILE, LIBRARY and SEARCH statements. 
it does not override the CLASS 
statement. 


Example: To assign all modules from 

the Fortran library to the first section 
except for segments in the module 
ENTX6L, which are assigned to the second 
(current) section: 


SECTION LIBRARY FORTRAN.LIB 
SECTION MODULE ENTX6L 


MODULE is most useful when applied to 
select modules from within a library. For 
example, selected library modules may be 
put into an overlay while the rest of the 
modules remain resident. 


Typically, the library manager sets the 
module name equal to the filename when 
an object file is inserted into a library. 

As a result, determining module names 
can be tricky and depends on the 
compiler. Fortran compilers typically set 
the module name as specified by the 
programmer, but some compilers give 
each module the same name, making 
MODULE impractical. 


Note: The DUMP utility program can 
identify the names of the modules 
in an object file. Use the INCLUDE 
option to specify module name 
(THEADR) records only in the dump, 
such as DUMP NAME.LIB INC 
THEADR. 


CONTINUED 
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Manual Segment Ordering, Continued 


STATEMENT | DESCRIPTION 
o e U 


The GROUP statement moves all segments 
within the specified group or groups into 
the current section. A group is a 
collection of segments to be accessed with 
the same segment register at execution 
time. 


Note: GROUP was used extensively in 
earlier versions of Plink86p/us to 
create a section containing only 
members of a particular group. This 
is done automatically. GROUP is now 
used to indicate a specific group 
order that overrides the default 
canonic segment ordering. 


GROUP overrides all section assignments 
! issued with the FILE, LIBRARY and 
j А SEARCH statements. It does not override 
the MODULE or CLASS statements. 


ДА ГЈ інен талы Кн кох 
i 


Example: To allocate all members of 
the groups DGROUP and COMGRP to the 
current section: 


GROUP DGROUP, COMGRP 


Note: All members of a group must reside 
within a single 64КВ memory area. 
This may not be possible if group 
members are scattered throughout 
several sections. The GROUP 
statement places all members of 
the group in the same section. 


00026 
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Status Line Display 


A status line can be displayed at the console while the program is 
being linked. The status line identifies the task Plink86p/us is 
currently performing. 


STATEMENT DESCRIPTION 


VERBOSE The VERBOSE statement displays the 
status line. VERBOSE has no arguments. 


The status line can slow down the linkage edit considerably. You 
may want to use VERBOSE only as you are learning how to use 
Plink86p/us or when you are trying to locate a problem during 
execution. VERBOSE should not be used on a teletype-like 
terminal as it will continuously rewrite the same line. 


Upper and Lower Case Letters 


By default, Plink86p/us also accepts identifiers and symbol names 
freely mixed in their origina! upper or lower case. The UPPER- 
CASE and LOWERCASE statements override this default. 


STATEMENT | DESCRIPTION 


LOWERCASE| The LOWERCASE statement forces all 
identifiers and symbol! names to lower 
case. 


UPPERCASE The UPPERCASE statement forces all 
identifiers and symbol names to upper 
case. 
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DOS 3.0 Memory Management 


Under normal operation, Plink86p/us allocates all free memory to 
a program when it is executed. The MEMORY statement allows 
use of DOS memory management features. MEMORY replaces 
the HIGH statement found in earlier versions of Plink86. 


STATEMENT| DESCRIPTION 


MEMORY The MEMORY statement specifies in 
16-byte paragraphs how much extra 
memory to allocate for the program. 
The value supplied by MEMORY is 
added to the value written at offset 
OAH (minimum extra memory needed) 
and then written to the .EXE file 
header at offset OCH. 


PlinkB&p/us by default places ЕРЕН in 
offset OCH of the .EXE header. This 
causes DOS to assign all available memory 
to the program. Attempts to allocate 
memory will then fail, as no more memory 
is available. Most high-level languages use 
a DOS SETBLOCK call during initialization 
to return memory not needed to DOS, 
making memory allocation functions 
possible. Programs written in these 
languages do not need the MEMORY 
statement. 


MEMORY specifies the maximum 
allocation beyond the memory required 
to load the program, including overlays 
and data areas. Remaining unallocated 
memory is then available for assignment 
by DOS memory calls. 


Example: To specify a maximum of 
1000 (hex) paragraphs of extra 
memory (64kB): 


MEMORY 1000 
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Disable Beeps 


Normally, a beep is sounded whenever Plink86p/us detects an 
error, or completes its processing. NOBELL overrides this 
default. 


STATEMENT DESCRIPTION 


NOBELL The NOBELL statement suppresses all 
beeps used with Plink86p/us processing. 


NOBELL has no arguments. 


Redirect Temporary Work File 


PlinkB6p/us automatically pages program descriptions to a tem- 
porary work file on disk if there is not enough memory available 
during processing. This file, named PLINK86.WRK by default, is 
created in the current directory. The WORKFILE statement over- 
rides this default. 


STATEMENT DESCRIPTION 


WORKFILE The WORKFILE statement specifies a file 
name for the Plink86 p/us temporary work 
file and optionally redirects it to a 
specified drive and path. 


Example: The Plink86p/us temporary work 
file is named TEMP.WRK and 
created in a Drive B subdirectory 
named SUB1. 


WORKFILEzZB:SUB1NTEMP. WRK 
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Change Comment Marker 


Earlier versions of Plink86p/us used the percentage sign '%' to 
indicate comment text in the statement input. The pound sign ‘#’ 
is now used to indicate comment text. The COMPATIBLE state- 


ment overrides this default. 


STATEMENT DESCRIPTION 
(EE eee —— ———XY! 


COMPATIBLE The COMPATIBLE statement changes the 
comment marker from ‘#’ to ‘%’ for 
compatibility with link files created for 
earlier versions of Plink86pl/us. 
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Microsoft Compatibility Statements 


Several Plink86p/us statements are required for some versions of 
compilers written by Microsoft. These statements correct minor 
incompatibilities in the Microsoft compilers: 


STATEMENT ERN ОШОО Он ӘҢ: O O OOO 


PM EE EUER ronanes e | The DSALLOC statement changes the 
address of the group DGROUP to be 
the size of the group minus 10000H. 


DSALLOC must be used when 
Microsoft Fortran and Pascal versions 
1.x or 2.x programs are linked. it is 
not required for programs linked under 
version 3.x of these languages. 
DSALLOC has no arguments. 


With DSALLOC, all items referenced 
relative to DGROUP will have offsets as 
though DGROUP were moved to the 
high end of the physical segment that 
holds the data area. At execution 
time, the run-time systems of the 


Microsoft Fortran and Pascal compilers 
move the DGROUP segments to a 
higher memory address before any 
references to them are made. 


NOSYMGROUP The NOSYMGROUP statement 
changes the way addresses are 
computed for certain references to 
external symbols in object files, disabl- 
ing an obscure feature of the 
Intel 8086 object format. 


NOSYMGROUP is only used when 
linking object files generated by 
Microsoft Fortran and Pascal version 
1.x and 2.x (but not version 3.x) 


CONTINUED 
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Microsoft Compatibility Statements, Continued 


STATEMENT 


NODEFLIB 


Chapter 4 - Operation 


DESCRIPTION 


The NODEFLIB statement suppresses 
automatic library search requests that 
are embedded in object files by 
Microsoft and other compilers. 
NODEFLIB has no arguments. 


The STACK statement changes the size 
of the stack defined in the .EXE file 
header to the number of bytes specified. 


Example: To create an 800 hex byte 
stack: 


STACK 800 


STACK is typically used to support 
Fortran compilers, including the Microsoft 
version 3.x Fortran compiler, the IBM 
Professional Fortran compiler and the 
Ryan McFarland Fortran compiler. 


With non-Fortran compilers, the stack is 
routinely discarded during execution and 
a new one built in available memory, so 
the STACK statement is not normally 

required. 
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Disable TYPDEF Record Processing 


TYPDEF record processing must be disabled when large pro- 
grams compiled with the Intel PL/M or Microtech Research 
Professional Pascal compilers are being linked. These compilers 
create TYPDEF records with a record size up to 1024 bytes, but 
Plink86p/us only recognizes record size up to 512 bytes. 


STATEMENT DESCRIPTION 


NOTYPCHECK The NOTYPCHECK statement disables 
TYPDEF record processing in Plink86p/us 
NOTYPCHECK has no arguments. 


Do not use NOTYPCHECK with Microsoft Fortran 3.3 or newer, 
with Microsoft C 3.0 or newer, or with Microsoft Pascal 3.3 or 
newer. Undefined symbols will occur. 
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МО Buffer Management 
Башы сіп әс д... аа атана 


DOS attempts to optimize certain I/O operations by executing 
them directly to or from the Plink86p/us l/O buffers. Unfortu- 
nately, some memory option cards are too slow for these 
operations because DMA transfers information to or from the 
hard disk. If the card isn't fast enough, DMA transfers FF or 00 
bytes instead of the correct data or it corrupts other data 
elsewhere on the card. Use the MAXBUFSIZE statement to 
correct this problem. 


STATEMENT DESCRIPTION 


MAXBUFSIZE The MAXBUFSIZE statement limits the 
size (in hex bytes) of the I/O operations 
Plink86p/us will perform. 


Example: To limit PlinkB&o/lus 1/О 


1 
| 
1 

| 


operations to 200 hex bytes: 
MAXBUFSIZE 200 


This forces DOS to use its own internal 
buffers for the operation. These buff- 
ers reside on the system memory board 
and are accessed correctly. 
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Validate Checksum 


The CHECKSUM utility program can validate the checksum of any 
.EXE file. The file CHECKSUM.EXE is required to execute this 


program. 


PROGRAM DESCRIPTION 
CL) eee eee 


CHECKSUM.EXE CHECKSUM adds all words in the file. 
if they produce OFFFFH, the message 
“Checksum OK” is displayed. If not, 
the checksum obtained is displayed 
with the message “Invalid Checksum”. 
This means the file has been 
corrupted somehow or is not really a 
.EXE file. 


The following example would validate 
the checksum of the file PLINK86.EXE. 


CHECKSUM PLINK86.EXE «cr» 
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The COMPARE utility program compares files. The file 
COMPARE.EXE is required to execute this program. 


PROGRAM DESCRIPTION 
OEN кл а) 


СОМРАНЕ.ЕХЕ COMPARE performs a byte-by-byte 
comparison of two files. Entire files 
or just portions of the files can be 
compared. When differences are 
found, mismatched bytes from both 
files are listed. If no extension is 
provided, compare defaults to .EXE. 


Example 1: To compare the files 
TEST.EXE and F1.EXE. The result is 
displayed at the console: 


COMPARE TEST F1 «cr» 


The COMPARE report can be copied 
to a disk file by including the DISK 
argument. The disk file is named 
COMPARE .DIF. 


Example 2: Compares the files 
TEST.EXE and F2.EXE and copies 
the results to the file COMPARE.DIF: 


COMPARE TEST F2 DISK «cr» 


Bi! 
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Dump Files 


The DUMP utility program copies the contents of a file to the 
console or to a disk file. The file DUMP.EXE is required to execute 
this program. 


PROGRAM DESCRIPTION 


DUMP copies the specified file in a 
variety of readable formats. 


The report format depends on the file 
type: 

-EXE: Header and all base fixups. 
.OBJ: Intel object record format. 


LIB: Each module in Microsoft of 
Intel object record format. 


.ASC: ASCII or "." for unprintable 
characters. 


For other file types, the dump is in 
hex with ASCII interpretation included 


for each line. File type .EXE is 
assumed if file type is not specified. 


Example 1: TEST.EXE is dumped 
to the console in .EXE format: 


DUMP TEST «cr» 


Base fixups are not included in the .EXE 
report by default. The FIXUP option 
reports the fixups. 


The dump report is displayed on the 
console by default. The DISK option 
copies the dump to a disk file instead. 
The file is named with the primary 
name from the file being dumped and 
the file type .LST. 


CONTINUED 
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Dump Files, Continued 


PROGRAM 


DUMP.EXE 
(continued) 


Chapter 4 - Operation 


DESCRIPTION 


Example 2: TEST.EXE could be 
dumped to a disk file TEST.LST in 
.EXE format with base fixups 
suppressed: 


DUMP TEST DISK «cr» 


Other dump options include the 
following: 


e MODULE <name> 
selects a single module for the 
.LIB report. 


SYMBOL «name» 
selects a single module where the 
specified public symbol is defined 
for the .LIB report. 


INCLUDE «name» 

includes records of the specified 
record types only. «names» is 
the Intel record names or hex 
record type numbers to include. 


EXCLUDE «name» 
excludes the specified object file 
record types. 


HEX 

forces a hex dump. The starting 
address and size may be specified 
with START «address» and SIZE 
«bytes» options. 


EXE forces a .EXE-type dump. 


OBJ forces a .OBJ-type dump. 


LIB forces a .LIB-type dump. 
ASC forces an ASCII format dump. 


Page 4-29 


CHAPTER 5 - OVERLAYS 


Overview 


This chapter describes how to set up and manage program 
overlays with Plink86p/us. 


Chapter Contents 
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Chapter Contents, Continued 
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Overlay Sections 


Overlays are sections of the program that share the same 
memory area. One overlay section overwrites another in the 
same memory space as each is required by the application 
program during execution. 


Overlays reduce the program’s total run-time memory require- 
ment. An application program that is larger than the total avail- 
able memory can be made to execute with overlays so that only 
those portions of the program required for the current function 
are resident in memory during program execution. 


For example, a text editor might have separate overlays that are 
individually loaded to perform edit and print functions. Since 
these functions are not required simultaneously, the program can 
execute in less memory. 


Overlays can be stacked hierarchically, much like the directories 
and subdirectories in the DOS directory structure. AS many as 
4,095 overlays can be stacked 32 levels deep. 


Independent overlay areas can be established, with each contain- 
ing groups of overlays that share the same memory address. 
Each overlay area can also have its own hierarchical overlay 
structure. 
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Overlay Considerations 
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An overlay loader is automatically included in the program when 
overlays are used. The loader reads the overlays from disk into 
memory as required by the program. 


A disadvantage with overlays is the extra time it takes to load 
them from disk during program execution. Efficient program 
organization and a fast overlay loader can minimize this problem, 
and the savings in memory is generally worth the slower execu- 
tion time. 


Also, if your program's target computer has enough memory 
available, a memory cache can be set up to store the overlays in 
memory when the program is executed. Overlays are then moved 
to the correct memory location when required by the program 
instead of being loaded from disk each time. With a memory 
cache, programs can be configured for a small memory machine 
that will execute faster on machines with greater memory. 


No explicit calls are required in the source code of the application 
program to load the overlays. They are loaded automatically by 
the overlay loader that is supplied with Plink86p/us. No license fee 
is required to sell software that contains this overlay loader. 


Application programs can also call the overlay loader directly by 
passing the number of the overlay to load. 


Most necessary changes to the overlay loader are achieved by 
modifying the user support module. Source code for this module 
is supplied with Plink86p/us in the file OVUSERM.ASM on the 
distribution disk. 


As a last resort, custom overlay loaders may be written to handle 
unusual circumstances. Technical details about how the loader 
works are included in Appendix C, "Overlay Loader." 
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Designing Overlay Structures 
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Arbitrary overlay structures are created without modifying the 
program source modules, but some rules concerning calling 


sequences and data access methods must be followed. These 
rules are discussed on the following pages. 


The overlay structure should be organized to minimize the num- 
ber of times overlays must be loaded into memory. For example, 
if a program loop that is executed 100,000 times has to switch 
from one overlay to another with each execution, program speed 
will obviously deteriorate to an unacceptable level. If each overlay 
E | is loaded in .06 seconds, this program would require three hours 
e { to execute. 


E | The goal in designing an overlay structure is to set up overlays 
containing functionally isolated areas of the program that will each 
execute to completion and then not be returned to for a long time 
if ever. 


The program executes much faster and in less space if each 
overlay section contains enough code to execute a complete 
program function. When the overlay’s function is completed, it 
may be overwritten by another overlay section that also executes 
a complete program function. 


The overlay remains in memory after it has completed execution. 
It is not overwritten until a request is made to load an overlay 
from the same overlay group in its place. 


Overlay sections are not stored back on disk when they are about 
to be overwritten. Instead, a fresh copy is loaded the next time 
the overlay is required. The overlay is never modified by the 
overlay loader or by the application program. Therefore, if you 
are overlaying data, be sure your variables are constant or only in 
use while the overlay is loaded. 
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Creating Overlay Sections 


The BEGINAREA and ENDAREA statements delineate areas of 
memory that will alternately contain different sections of code. 
Sections created between the BEGINAREA and ENDAREA pair 
automatically become overlays that share the same memory 
space. BEGIN and END have no arguments. 


STATEMENT DESCRIPTION 


BEGINAREA The BEGINAREA statement creates an 
overlay area starting at the current 


memory allocation address. 


ENDAREA The ENDAREA statement indicates the 
end of the overlay area. 


The following example shows how a simple overlay area is 
created. 


Example #1: OUTPUT TEST.EXE FILE F1 
BEGINAREA 
SECTION FILE F2 
SECTION FILE F3 
SECTION FILE F4 
ENDAREA 
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Creating Overlay Sections, Continued 
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This example creates a program named TEST.EXE consisting of 
four sections: 


e F1 is the root section, which is always resident in mem- 
ory. There is no SECTION statement issued for the root 
because Plink86p/us creates a section automatically when 
the FILE statement is encountered. All modules in F1 are 
placed into this section. The overlay loader also resides in 
this section. 


e F2, F3 апа F4 are overlay sections because they appear 
within the BEGINAREA and ENDAREA statements. These 
sections are explicitly created with the SECTION state- 
ment. They share the same address in memory and are 
loaded by the overlay loader as required. 


e Data overlay is a preloaded overlay created at the end of 
the program for data. 


When TEST.EXE is executed in Example #1, the root section only 
is loaded by DOS and execution begins. The operating system is 
not even aware of the overlays at the end of the program. When 
a call is made to some code from file F2, the overlay loader is 
automatically invoked to read that overlay from the disk and then 
a branch is made to the called routine. 


A second overlay area is created by issuing a new pair of 
BEGIN/END statements. This overlay will be created in the next 
available space in memory after the first overlay area. 


Creating Overlay Sections, Continued 
OS a es | 


With multiple independent overlay areas, overlays from different 
areas can reside in memory simultaneously. For instance, 
Example #2 could be appended to Example #1: 


Example #2: BEGIN 
SECTION FILE F5 
SECTION FILE F6 
SECTION FILE F7 
END 


File F2 in Example #1 could now call file F6 in Example #2 
because the overlays containing these files are in different 
overlay areas. 


The number of independent overlay areas that may be created is 
limited by the number of sections and objects. Each area can 
have its own hierarchical overlay structure, with the size of each 
area determined by the size of its largest section. 
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Plink86p/us arranges for overlays to be loaded automatically by 
inserting a small piece of code that calls the overlay loader in the 
place of addresses that point to overlaid routines. This piece of 
code is called the overlay vector. lt insures that the proper 
overlay is in memory and then jumps to the overlaid routine. 


The overlay loader uses the program's stack area, but restores 
the stack and all machine registers to their prior state before 
returning control to the program. Programs can either call or 
jump to overlaid routines. Calls are normally used. They can be 
either short or long. 


Automatic overlay loading is defeated when the routine returns to 
its caller if the caller is not still in memory. For example, if F2 calls 
F3 in the previous example, F2 will be smashed by F3 before the 
return to F2 is made because F3 occupies the same memory 
location. A program bug would result when F3 attempts to return 
to F2. 


The RELOAD statement alleviates this problem by automatically 
reloading the calling overlay if it has been overwritten. RELOAD is 
described later in this chapter. 


If RELOAD is not used, you must insure that the caller is still in 
memory when the return is made. The correct procedure in the 
previous example would be to have the root call F1, F2, and F3 
instead of calling F3 from F2. 
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How Overlays Work 
I _ ыш ЕЕЕ ЕСС 


The memory diagrams that follow illustrate how the overlay 
Structure appears in memory. In these diagrams, the vertical 
dimension represents memory addresses in ascending order. 
The horizontal dimension indicates where memory locations are 
shared. 


Figure 5.1 illustrates the result of the following Plink86p/us input: 


OUTPUT TEST 1 
FILE F1 
BEGINAREA 
SECTION FILE F2 
SECTION FILE F3 
SECTION FILE F4 
ENDAREA 


«— Shared Memory Locations —» 


Highest 
Address 


T 
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Lowest 
Address 


Figure 5.1 A Simple Overlay Structure 


F1 continues all the way from left to right because it is resident 
and does not share its memory. F2, F3 and F4 are overlays that 
share the same memory space within the overlay area. Since F3 
is larger than F2 and F4, some memory is unused when those 
overlays are in memory. These wasted areas are not shaded in 
the diagram. 
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Multiple Overlay Areas 
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Figure 5.2 illustrates the result of the following PlinkB6p/us input: 


OUTPUT TEST 2 
FILE FMAIN 
BEGIN 
SECTION FILE F1 
SECTION FILE F2A,F2B,F2C 
SECTION FILE ЕЗ 
END 
BEGIN 
SECTION FILE F4 
SECTION FILE F5 
SECTION FILE F6 
END 


«— shared Memory Locations —» 


Highest 
Address 


Address 


Figure 5.2 Multiple Overlay Areas 


Two independent overlay areas are created here. The second 
area is created above the first at the next available memory 
space. An overlay from the first area and an overlay from the 
second area can reside in memory simultaneously. F1 could call 
F6 since the overlays are in different areas. Note that F2A, F2B 
and F2C are in the same section and are loaded as a single unit. 
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Nested Overlays 


Figure 5.3 illustrates the result of the following Plink86p/us input: 


OUTPUT TEST3 

FILE FMAIN 

LIB FLIBR 

BEGIN SECTION FILE F1 
SECTION FILE F2 
BEGIN 


SECTION FILE F4 
SECTION FILE F5 
SECTION FILE F6 


END 
SECTION FILE F3 


«— Shared Memory Locations —» 


Highest 
Address 


"Resident Section 


Lowest EMAIN + festa 
Address ... (FMAIN + Overlay Loader) 


Figure 5.3 Nested Overlay Structure 


Nested overlay areas (i.e., overlay areas within overlay areas) 
are created here because the second BEGINAREA statement 
appears before the first ENDAREA statement. The memory that is 
shared by the nested overlay areas (F4, F5 and F6) is only 
available to them when F2 is already loaded. 
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Every section of а program is assigned a level number. This is to 
accommodate nested overlays, which may be as many as 32 
levels deep in each overlay area. 


Nested overlay structures are useful when a set of routines is only 
used by certain overlays. In Figure 5.3, for example, F2 would 
typically contain routines used by F4 through F6 but not by F1 or 
F3. 


Plink86p/us will not allow you to place the same module in two 
different overlays, because duplicate public symbols would result 
(i.e., there is only one symbol table for the entire program). 
Nested overlay structures offer a means to place these routines 
into an overlay at a lower level without making them permanently 
resident. 


Each overlay’s leve! number is significant because it corresponds 
with the number of “ancestors” the overlay has, and each of 
these ancestors must already reside in memory before the 
overlay can be loaded: 


ө The overlay's immediate “ancestor” is the last section 
defined prior to the beginning of the overlay area at a 
lower address. In Figure 5.1, the ancestor of F2 is F1. 
FMAIN is the ancestor of all Figure 5.2 overlays. 


o The overlay's family of "ancestors" is the ancestor, the 
ancestor's ancestor, etc., until a resident section is 
reached. In Figure 5.3, the ancestors of F4 through F6 
are F2 and then FMAIN. 


Conversely, the section's "descendants" are all sections that 
have it as an ancestor. In Figure 5.3, the descendants of F2 are 
F4, F5 and F6. 


Resident sections are assigned a level! number of zero. The level 
number is increased by one when a BEGINAREA statement is 
entered and then decreased by one at the next ENDAREA 
statement. 
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Overlay Level Numbering, Continued 
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In the previous examples, each section’s level number would be 
assigned as follows: 


Figure 5.1: OUTPUT TEST1 


(level O) FILE F1 
(level 1) BEGINAREA 


(level 1) SECTION FILE F2 
(level 1) SECTION FILE F3 
(level 1) SECTION FILE F4 


(level 0) ENDAREA 


Figure 5.2: OUTPUT TEST2 


(level 0) FILE FMAIN 
(level 1) BEGIN 


(level 1) SECTION FILE F1 

(level 1) SECTION FILE F2A, F2B, F2C 
(level 1) SECTION FILE F3 

(level 0) END 

(level 1) BEGIN 

(level 1) SECTION FILE F4 

(level 1) SECTION FILE F5 

(level 1) SECTION FILE F6 


(level 0) ^ END 


Figure 5.3: OUTPUT TEST3 


(leve! 0) FILE FMAIN 
(level 0) LIB FLIBR 


(level 1) BEG SECT FILE F1 
(level 1) SECT FILE F2 
(level 2) BEG 
(level 2) SECT FILE F4 
(level 2) SECT FILE F5 
(level 2) SECT FILE F6 
(level 1) END 
(level 1) SECT FILE F3 
(level 0) END 
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Placing Data into Overlays 


Plink86plus allows you to place data into OVERLAYS by using the 
OVERLAY and SECTION statements. 


STATEMENT | DESCRIPTION 


SSS eS ЕЗ ЛШ ОИЫН ШШЕН нйн Шы жы сш ушыш хш шш ------ mE ум | 
Syntax: 
OVERLAY OVERLAY <classname> [, <classname>] 


Segmenst in the specified class are put in 
the overlay structure as defined by FILE, 


LIBRARY and MODULE statements. 


SECTION Only segments with the same class name 
as the first segment in the first file are 
put in the overlay. All other segments are 
placed in data overlays. 


Plink86p/us places data segments in a resident overlay at the end 
of the program by default. If the data segments were mixed with 
code segments in the overlays, it would usually not be possible 
for the lowest one in memory to be within 64kB of the high end of 
the last one in memory. 


Another problem is caused by the run-time support systems for 
some versions of the Microsoft Fortran and Pascal compilers. 
These systems move the data areas as the program begins 
execution. As a result, data segments in the overlays would not 
be moved to the right spot and would not work correctly. 


Also, overlay sections are not stored back on disk when they are 
about to be overwritten. Instead, a fresh copy is loaded the next 
time the overlay is required. Therefore, if you are overlaying 
data, be sure your variables are constant or only in use while the 
overlay is loaded. 
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An overlay cache is an area of memory reserved for overlays. 
Plink86p/us can create an overlay cache in regular DOS memory, 
in extended (80286 protected mode) memory, or in expanded 
(Lotus-Microsoft-Intel bank-switched) memory. 


The cache will not overwrite memory which has previously been 
allocated and will not grow larger than the total size of all 
non-resident overlays. When the program has finished executing, 
the cache area is returned to available memory. 


Overlay caching allows programs to contain an overlay structure 
designed for a small-memory PC-type computer that will also 
execute faster on a larger-memory PC-AT-type computer. 


When the program is executed on a smaller machine, the 
overlays are individually loaded from disk when required by the 
program. When the same program is executed on a larger 
machine, overlays can be loaded to the cache area when the 
program is executed and then moved to the correct memory 
address when required without requiring any additional disk 
access. 


All cache requests are reported in a table on the MAP report. This 
table lists for each cache memory type the amount of memory 
requested for the cache and reserved for the application. 


Note: Programs that fork child processes may return the cache 
memory to DOS by calling $OVCOFF before forking. Pro- 
grams that terminate and stay resident may attempt to 
use caching by calling $OVCOFF before terminating and 
then calling $OVCON on activation. 
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Overlay Memory Caching, Continued 


The CACHE statement sets up memory caching: 


STATEMENT | DESCRIPTION 


CACHE The CACHE statement creates an overlay 
cache by loading an overlay loader that 
determines available memory and uses 
a portion of it for overlays. 


CACHE Arguments specify the CACHE 
type and size. 

REGULAR | Regular DOS memory 
(the default) 

EXTENDED| Extended (80286) protected 
mode) memory. 

LIM Expanded (Lotus-Intel- 
Microsoft bank-switched) 
memory. 


Only one cache type can be specified per 
CACHE statement, but more than one 
CACHE statement can be used in the 
input. Multiple statements give a program 
the ability to create an appropriate cache 
type on a variety of different hardware 
configurations. 


When multiple statements are used, 
Plink86p/us looks first for LIM expanded 
memory. If that memory is not present 
(or if it contains insufficient memory for 
the cache), Plink86p/us looks for 

extended memory. If that memory is not 
available, Plink86p/us looks for DOS regular 
memory for the cache. If, after all this, 
there is not sufficient DOS memory 
available, no cache is created. 
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Automatic Overlay Reload 


The RELOAD statement causes the overlay loader to automati- 
cally reload an overlay that was overwritten by a previous call. For 
example, if A.OVL calls a function in B.OVL and B.OVL overlays 
A.OVL, the system will hang when the program attempts to return 
to its caller, A.OVL. With RELOAD, A.OVL reloads automatically. 


RELOAD will not work with compilers whose assembly language 
function arguments are not pushed on the stack. These argu- 
ments appear “in line” after the function call instruction and are 
accessed via the return address in the stack. However, RELOAD 
substitutes a return address that points inside the overlay loader 
and not to the function arguments. 
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Automatic Overlay Reload, Continued 


STATEMENT | DESCRIPTION 


RELOAD The RELOAD statement replaces the 
real function return address in the user 
stack with the address of a routine that 
performs the reloading procedure. An 
internal reload stack tracks the calls 
from one overlay to another so it knows 
which one to reload. 


RELOAD parameters allow you to specify 
the stack depth and state if the code is 
near or far. (NEAR or FAR-must match 
your compiler’s setting or unpredictable 
results can occur.) 


Stack depth is the amount of memory 
to reserve for the stack, calculated as 
the maximum number of nested calls 
(in hex) made to overlaid functions 
during program execution, multiplied by 
six bytes. If the requested stack space 
is not available or if the stack overflows, 
the program is terminated. 


In the following example, reloading is set 
for NEAR code with a 100 (hex) call 
stack using 600 (hex) bytes: 


RELOAD NEAR 100 


Note: Using setjimp/longimp when 
RELOAD (or TRACK) is invoked 
can create problems for the іп- 
ternal stack. Also, a longjmp into 
a non-resident overlay will cause 
a program crash. However, pro- 
cedures from OVERLAY.LIB may 
be used to save and restore the 
current overlay and reloading con- 
text. Refer to Appendix C, “Оуег- 
lay Loader" for information about 
modifying the assembler file 
OVSTACK.ASM. 
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Automatic Overlay Reload, Continued 
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STATEMENT| DESCRIPTION 


RELOAD Warning: 


(continued) Do not use RELOAD when ALLOCATE 
is used on a large code model. Some 
run-time libraries mix far and near calls. 
The program may not run if these 
library routines are more than 64kB from 
the overlay table. The run-time libraries 
of some compilers contain routines that 
manipulate the return address of the 
stack. These routines are incompatible 
with RELOAD. If your program crashes 
when you use RELOAD, try linking it 
without the RELOAD statement. If it 
works without RELOAD, NOVECTOR the 
run-time library. Be sure the name you 
give NOVECTOR is exactly the same as 


f 
1 
i 

i 

$ 

! 

! 


the name іп your LIBRARY or SEARCH 
statement. If the program still crashes 
with RELOAD, your compiler is generating 
code that manipulates the stack directly, 
and RELOAD cannot be used. 


Microsoft 
C Note: 


Reloading with a small model application 
requires use of the large model syntax 
(RELOAD far stack depth). Since the 
run-time libraries mix far and near calls, 
the far syntax must be used to cover 
both cases. If a near call cannot be 
vectored, the module that refers to it 
must be moved to within 64kB of the 
start of the overlay table. 


ie m imt e 
а аа. 
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Reload Selected Symbols Only 


RELOAD causes the overlay loader to automatically reload all 
overlays that were overwritten by previous calls. The TRACK 
statement provides a restricted version of this feature, the same 
as if RELOAD FAR were enabled but for selected symbols only. 


STATEMENT DESCRIPTION 


TRACK The TRACK statement enables overlay 
reloading for selected symbols only. This 
can improve response time for some 
applications. Symbols selected by 


TRACK are vectored both up and down 
the overlay structure. 


The following example activates auto- 
matic reload for $1, $2, and $3 only, 
with a 100 (hex) call stack depth: 


TRACK 100 $1, $2, $3 
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Preload Overlay Sections 


Overlays can be preloaded into memory before the user program 
gains control. The PRELOAD statement controls this process. 


STATEMENT| DESCRIPTION 


PRELOAD The PRELOAD statement instructs the 
overlay loader to preload a specified 
overlay section into memory before 
contro! is passed to the user program. 
Normally, only permanently resident 
sections of the program (such as the root 
and data) are located before the user 
program takes control. 


PRELOAD is inserted in the statement 


input immediately following the SECTION 
statement for the overlay section to 
preload. PRELOAD has no arguments. 


The following example preloads section 
OV2 into memory before control is 
passed to the program: 


OUTPUT TEST. EXE 

FILE F1.OBJ, Ғ2.ОВ.) 

BEGINAREA SECTION = OV1 FILE A 
SECTION = OV2 PRELOAD FILE B 
SECITON = OV3 FILE C 

ENDAREA 
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Automatic Library Module Allocation 


A program’s run-time memory requirement can be reduced by 
not linking the entire library file into the root of the overlay 
structure. The ALLOCATE statement controls this process. 


STATEMENT | DESCRIPTION 


ALLOCATE The ALLOCATE statement sets modules 
in selected libraries as automatically 
available to the overlay structure. With 
ALLOCATE, individual library modules 
are parceled out to the overlay structure 
to occupy memory space only when and 
where they are needed during execution. 


Each segment from an allocated library 
is placed in the overlay structure at a 
point where it is an ancestor or 
descendent of all overlays it calls or is 
called by. 


Example: The libraries LIB2, and LIB3 are 
identified as being available for automatic 
allocation of modules: 


ALLOCATE LIB1, LIB2, LIB3 


When the VERBOSE statement is used 
with ALLOCATE, each segment that is 
assigned by Plink86-Plus to a section 
other than the root is listed at the 
console. 


ALLOCATE may not work properly on 
Microsoft C applications because the 
run-time libraries mix near and far calls 
and ALLOCATE might inadvertently place 
modules more than 64kB apart. If a near 
call cannot be vectored, the module that 
refers to it must be moved to within 64kB 
of the start of the overlay table. 
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Separate Overlay Files 
SOOO 


Normally, the resident portions of the program and all overlays 
are written to the same output file. The overlays appear at the 
end of the file and the operating system is not aware of their 
presence when loading the program. 


Since the program file is opened only once, it executes faster 
because a directory search is not required to find the overlay 
files. Also, problems caused by mixing overlay files from different 
versions of the program are avoided. 


Placing overlays in separate disk files is still useful under some 
circumstances. For example, some programs cannot fit on a 
single floppy disk, so overlays could be put in separate files on a 
separate disk. Also, you could sell the program as a number of 
separate packages with the overlay files sold apart from the main 
program file. 


Overlays are placed in separate disk files with the SECTION 
statement’s INTO option. SECTION INTO specifies the name of a 
disk file to put the overlay section in. If the file type is not 
specified, type .OVL is used. 


When the INTO option is omitted, the file is written to the file of its 
ancestor or to the main output file if it is at level zero. 


In the following example, the program from Figure 5.1 is written 
to three disk separate disk files, where F1 and F4 are in 
TEST.EXE, F2 is in TEST1.OVL and F3 is in TEST2.OVL: 


OUTPUT TEST 


FILE F1 

BEGIN SECTION INTO TEST1 FILE F2 
SECTION INTO TEST2 FILE ЕЗ 
SECTION FILE F4 

END 
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Copy Protection Considerations 
EIA 


If you are using a copy protection package on your program, you 
may have to modify the way it is linked. Copy protection schemes 
typically encode the .EXE file and add a decoding routine at the 
front. This routine determines if it is permissible to execute the 
program and decodes it back to its original form. 


lf Plink86p/us overlays are being used, however, the file will 
contain more than just the binary image of the program. The 
overlays are placed at the end of the .EXE file. 


The copy protection program usually encodes the entire file, 
including the overlays, which then will not execute. If the overlays 
are moved to a separate file (using SECTION INTO), the .EXE file 
will contain only the loadable image of the program and can be 
encoded and decoded properly. 


Sections that Plink86p/us creates automatically go into the .EXE 
file. For example, in most cases it is necessary that data 
segments for a program be located at the end of the program in 
memory, so Plink86p/us creates this section after the last overlay 
area. 


To get this section out of the main executable file, use the 
SECTION statement yourself before Plink86p/us decides that a 
new section is required. For example, "SECTION = DATA INTO 
TESTOV" after the last END statement would move the DATA 
section to the file TESTOV before Plink86p/us could create а 
section to hold the data segments and place it in the .EXE file. 


Note: Symbol tables created with the SYMTABLE statement 
also appear in the .EXE file and must be removed before 
copy protection schemes can be used. The SYMTABLE 
utility program can delete the symbol table. 
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Finding Overlay Files 


Program overlays are normally contained in the same file, so the 
overlay loader must find and open this file. 


If the overlays are contained in one or more separate files, the 
overlay loader must find these files as well. This process is 
usually automatic, but occasionally the operator may be asked to 
tell the program where the overlays are. 


Plink86p/us supplies the overlay loader with a common block 
containing the names of all files that make up the program. These 
file names consist of a name and type only. The device (drive 
and directory) names are stripped off. 


To find an overlay file, the overlay loader sequentially checks the 
current directory in the current default disk drive, the directories 
listed in the directory PATH and the internally set “overlay file 
prefix." This string (defined in the overlay loader's user support 
module) is appended to the front of the overlay file. For DOS 3.0 
or newer, the loader checks the directory portion of the original 
DOS command that loaded the program before checking the 
directory path. 


If the file still cannot be located, the operator is asked to enter a 
file name prefix, which can be a drive and/or a path name. This 
prefix is stored and used to find other overlays later. 


The operator can change diskettes here if necessary, but only if 
there are no open files on the current disk. 


To minimize diskette changes, it is best to put the program file 
and all overlay files in the directory specified by the PATH string in 
the environment. You can also modify the overlay loader's 
internally set overlay file prefix to specify a search path. 


See Appendix C and OVUSERM.ASM supplied on disk. 
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Display Overlay Status 


Рііпк86р/иѕ can display the overlay number at the console as 
each overlay is loaded during program execution when the 
DEBUG statement is included in the input. This provides a 
convenient method for testing and debugging overlays. 


STATEMENT | DESCRIPTION 


The DEBUG statement displays the overlay 
number at the console as each overlay is 
loaded. When used with a link map, 
DEBUG allows you to follow.the overlay 


process at each step while the program 
executes. 


Example: To execute Plink86p/us with 
input from the file TEST.LNK and load the 
version of the overlay loader that displays 
a message as each overlay is loaded. 


PLINK86 DEBUG @TEST.LNK 


Selecting an Overlay Loader 


The overlay loader library must reside on disk in a file named 
OVERLAY.LIB. This file is supplied on the Plink86p/us distribution 
disk. 


OVERLAY.LIB contains several versions of the overlay loader. The 
standard version is selected automatically except when the 
DEBUG statement is used to specify the version that includes 
debugging messages, when the CACHE statement is used to 
specify the version that supports memory caching, etc. 


Note: OVERLAY.LIB is searched by Plink86p/us as required 
during execution. It should not be input from a FILE, жы 
LIBRARY ог SEARCH statement. Instead, put { 
OVERLAY.LIB in a directory defined in the DOS SET OBJ 
environment string so Plink86p/us will be able to find it. | 


Page 5-28 Ріпк86 plus User Manual 


Override Automatic Overlay Loading 


Several Plink86p/us statements override how the overlay loader 
handles certain situations. These statements are OVERLAY, 
ALWAYS, NEVER апа NOVECTOR . 


STATEMENT} DESCRIPTION 


OVERLAY 


The OVERLAY statement overrides the 
normal class placement method by placing 
the specified classes into overlaid sections 
of the program. OVERLAY takes as 
arguments the names of the segment 
classes to be marked as overlayable. All 
other classes are moved to the end of 

the program as before. 


This is useful when modules containing 
both code and data segments are being 
placed in overlays by the FILE statement. 
Usually, only the code segments should go 
into the overlay. 


Plink86 p/us normally places the first class 
defined by the program modules into the 
overlay structure and moves all other 

classes to the very end of the program. 


This is usually correct because most 
compilers place the class containing code 
segments first. Also, the data area is 
placed at the end of the program because 
most compilers allocate heap space at the 
end of the data area. This placement 
method allows the heap to grow into free 
memory. 


If this placement is not correct, the 
OVERLAY statement can specify classes 
that will remain in the overlay structure. 

OVERLAY allows you to list these classes 
in the statement input. 


CONTINUED 
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Override Automatic Overlay Loading, Continued 


STATEMENT 


OVERLAY 
(continued) 


ALWAYS 
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DESCRIPTION 


The OVERLAY statement will most often be 
needed for one of the following instructions: 


o There is more than one class containing 
code segments. Place all classes con- 
taining code into overlays in the order 
you desire by inserting an OVERLAY 
statement specifying all code classes 
as arguments in the correct order. 


ө The class containing code is not the 
first class defined in the compiler's 
output. Use an OVERLAY statement 
with the name of your code class or 
classes as argument. 


o You wish to overlay data. Use an 
OVERLAY statement with the names 


of your code and data classes as 
arguments. See "Placing Data Into 
Overlays" on Page 5-15. 


The ALWAYS statement forces the 
overlay structure to always use the symbol 
vector address for references to a 
specified symbol in different sections. 


Normally, when an address in Section 

A is a reference to a symbol in Section B, 
Plink86p/us subsitutes the symbol vector 
address for the real address. However, 

the real address is retained when A is a 
descendant of B. ALWAYS causes Plink86p/us 
to substitute the symbol vector address 

for the real address in references to the 
specified symbols under all circumstances. 
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Override Automatic Overlay Loading, Continued 


STATEMENT | DESCRIPTION 


NEVER The NEVER statement forces the overlay 
structure to never use the symbol vector 
address for references to a specified 
symbol in different sections. The real 
address is used instead. 

This is useful if the symbol represents 

data instead of code. Plink86p/us assumes 
by default that a function is being accessed 
and uses the symbol vector address, causing 
a program bug. 

NEVER causes Рііпк86р/иѕ to always use the 
real address (never substitute the symbol 
vector address) for the specified symbol 

or symbols. 

Note that NEVER is normally not required for 
symbols representing data because those 
symbols are ordinarily in non-overlaid classes. 


NOVECTOR | The NOVECTOR statement effectively 
sets the NEVER statement for all symbols 
in specified files only prohibiting Plink86p/us 
from vectoring any of those symbols. 
NOVECTOR can improve program exe- 
cution time, expecially when used in con- 
junction with the RELOAD statement. 
All calls outside the section will be vectored 
during RELOAD, but NOVECTOR will 
inhibit vectoring for those symbols in the 
root that do not load overlays. 
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Overlay Loader Support Module 
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The overlay loader consists of a disk loader module апа а user 
support module. Source code is supplied for the user support 
module, but not for the disk loader module. 


The user support module performs all operator interaction, 
makes decisions about where and how to look for overlay files, 
and controls how the loader behaves in a networking environ- 
ment. PlinkB6p/us console messages are also contained in the 
support module. 


Source code for the standard user support module used by 
OVERLAY.LIB is included in the disk file OVUSERM.ASM in the 
OVERLAY directory on the  Plink86p/us distribution disk. 
OVUSERM.ASM may be assembled with Pasm or with Masm 
version 3.0 or 4.0. 


To customize how the overlay loader operates, you can modify 
and reassemble OVUSERM.ASM and link it in to your application. 
Virtually all modifications required to make your application run 
more efficiently can be accomplished with minor changes to the 
OVUSERM.ASM code. 


Note: А simplified support module that may suffice for many 
applications is included in the disk file SAMPLE.ASM in the 
OVERLAY directory on the PlinkB6p/us distribution disk. 


Refer to Appendix C, "Overlay Loader" for more information 
about customizing the user support module. 
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Direct Overlay Loading 
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It may be necessary to call the overlay loader directly from the 
application program under some circumstances. One example is 


when the automatic overlay load for a call to a symbol in an 
overlay has been suppressed by the NEVER statement. 


The associated overlay must be loaded manually before calling 
the symbol. 


Direct overlay loading is also desirable in situations where the 
application program should handle an “overlay not found” prob- 
lem by itself. This allows greater marketing flexibility at the 
expense of a completely automated overlay load. 


For example, if the overlay is sold as an optional separate portion 
of the program, the application might output a message like “The 
separately sold file LEDGER.OVR is required for the general 
ledger program” if users attempt to use parts of the program 
they do not have. 


Assembly language must be used to call the overlay loader 
directly. This choice was made because different compilers use 
incompatible methods of passing parameters to procedures and 
returning function results. 


The code required for manually loading overlays under DOS is as 
follows: 


extrn SLOADS:far 


mov АН, <рагатеїег> 

тоу СХ, <питбег of overlay to load» 
call $LOAD$ 

jc «error routine» 
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Direct Overlay Loading, Continued 
ПЕНЫ 


When $LOADS$ is called, the overlay whose number is CX and ай 
of its ancestors will be loaded into memory if not already there. 
Any routines in the overlays can then be called in the normal 
fashion. 


The overlay number is determined strictly by the order the 
overlays are defined in the Plink86p/us input. This sequential 
numbering is used regardless of what level the overlay is on. 


Note: |f you are unsure about how the overlay numbers will be 
assigned, refer to the MAP S (or MAP A ) report. 


The parameter in AH tells the overlay loader what it should do 
when it cannot find an overlay file: 


ө if AH is zero, the program is terminated. The overlay 
loader support module has an opportunity to issue a con- 
sole message before this happens. This message can ex- 
plain why the program is terminating, for example, 
such as the absence of a separately-sold overlay file to 
perform the requested function. 


e |f AH is non-zero, the loader returns from the $LOAD$ 
call with the carry flag set. 
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CHAPTER 6 - SYMBOLS 


Overview 
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This chapter describes how symbols are handled by Plink86p/us. 
Symbol tables and symboi management techniques are also 
discussed here. 
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Symbol Types 


A symbol is an identifier in a program. It is a name for a value. 
The value may be a constant or the address of a piece of code or 
data somewhere in the program. 


A symbol representing a known, constant address is called an 
absolute symbol. A symbol representing a relocatable address is 
called a relative symbol (i.e., it is defined relative to a segment). 


When segments contain references to a symbol, PlinkB6p/us 
"fixes up" those references to contain the assigned address as 
soon as it is known. For example, if a segment is 100 bytes long, 
a relative symbol could be defined as the' address of that 
segment plus 50 bytes. PlinkB6p/us calculates the address of the 
symbol! by adding 50 to the address it selects for the segment. 


Symbols are also referred to as public symbols, global symbols, 
internal symbols, external symbols, local symbols, etc. Some of 
these (such as global and public) mean the same thing. The 
symbol type often depends on the perspective of the symbol's 
user. For example, a public symbol defined in one module is seen 
as an external symbol by another module that uses it. 


Global symbols or public symbols are symbols whose address is 
designated by the compiler as available for modules other than 
the module that defines them. This is useful for sharing proce- 
dures and variables among modules. 


Only those symbols deliberately made public by the compiler are 
visible to other modules. If more than one module makes a given 
symbol public, a duplicate symbol warning message is issued by 
Plink86p/us. Each symbol should have only one definition. 


Local symbols are symbols that are not made public to other 
modules. These symbols are only used by the module that 
defines them. 
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Symbol Types, Continued 


External symbols are symbols that are not defined in a module 
that references them. This is what public symbols are called from 
inside a module that depends on another module to supply the 
symbol value. 


All references to external symbols are fixed up by Plink86p/us 
when their values become known. If an external symbol is not 
defined by any module, Plink86p/us issues an error message and 
exits. 


Create a Symbol Table 


| 

| 

| PlinkB6p/us can append а symbol table to the .ЕХЕ output file that 
| is created to hold the linked program. This symbol table provides 
| information about the names and addresses of symbols in the 
program and is used by the PfixB6plus symbolic debugger and 
Pfinish program optimizer. 


STATEMENT DESCRIPTION 


SYMTABLE 


The SYMTABLE statement creates a 
symbol table and appends it to the .EXE 
file. SYMTABLE has no arguments and 
can appear anywhere in the input. 


Example: To append a symbol table 
to TEST.EXE: 
OUPUT TEST.EXE 


FILE F1 
SYMTABLE 


Pfix86p/us adds the symbols to its display windows to make the 
assembly language code and hex data displayed there more 
readable. The symbol table also provides Pfix86p/us with informa- 
tion about overlays, enabling the debugger to handle tasks like 
setting break-points in overlays not currently in memory. Pfinish 
uses the symbol table to display symbol names instead of 
addresses when program performance is analyzed. 
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Include or Exclude Symbol Types 


Under normal operation, the SYMTABLE statement loads all 
symbols in all modules of the input files into the symbol table. 
However, for large programs, the symbol table might become too 
large for the Pfix86p/us debugger to handle. Тһе GLOBALS, 
LOCALS and NOLOCALS statements exclude all or selected 
symbols from the symbol! table. 


STATEMENT} DESCRIPTION 


GLOBALS The GLOBALS statement includes selected 
global (public) symbols only in the symbol 
table. GLOBALS can include public 
symbols from specified files or specified 
modules only. It can also include speci- 
fied symbols only. GLOBALS suppresses 
loca! symbols. 

The following example includes all global 
symbols from the file LIB1.LIB and from the 
module F1.OBJ. All global symbols іп 
F2.0BJ and LIB2.LIB are excluded except 
COS: 

OUTPUT TEST.EXE FILE F1.0BJ, F2.0BJ 
LIBRARY LIB1.LIB, LIB2.LIB SYMTABLE 
GLOBALS FILE LIB1.LIB 

GLOBALS MODULE F1 

GLOBALS SYMBOL COS 


LOCALS The LOCALS statement includes local 
symbols and line numbers from specified 
modules only in the symbol table. LOCALS 
does not affect public symbols. LOCALS 
will include local symbols from specific 
modules. if the following statement is app- 
ended to the previous example, the only 
local symbols included in the symbol table 
are from modules named SIN and TAN: 


LOCALS SIN, TAN 


NOLOCALS The NOLOCALS statement eliminates all 
local symbols and line numbers from the ( 
symbol table. NOLOCALS does not affect 
public symbols. It has no arguments. 
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Print or Delete a Symbol Table 
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The SYMTABLE utility program prints or deletes a symbol table. 
The disk file SYMTABLE.EXE is required to execute this program. 


The file identified as an argument in SYMTABLE is searched fora 
symbol table. This file must have a file type of .EXE. An error 
message is displayed if the file cannot be found, if it does not 
have a .EXE file type or if it does not contain a symbol table. 


OPTION DESCRIPTION 


PRINT When the requested .EXE file is found, 
Table the symbol table is printed automatically 
at the console. 


Example: To print the symbol table 
for TEST.EXE. 


SYMTABLE TEST.EXE <cr> 


Symbol tables can also be deleted with 
the SYMTABLE utility program by 
including the DELETE (or DEL) 

option in the command input. 


Example: To delete the symbol table 
from TEST.EXE: 


SYMTABLE TEST.EXE DELETE <cr> 


This is useful if your program has been 
debugged and you don't want to relink 
it just to remove the symbol table. 


When DELETE is used, the .EXE file is 
renamed as file type '.$$$', and is the 
temporary file. The .EXE file is deleted. 
The ‘$$$’ file is renamed as the .ЕХЕ 

file, with the symbol table omitted. The 
program terminates if there is not en- 

ough disk space for the .$$$ work file. 
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Resolve External Symbol References 


Plink86p/us can fix up references to symbols that are not defined 
by any module in the program. Use the DEFINE statement to 
resolve references to external symbols by assigning a value to 
them. 


OPTION DESCRIPTION 


DEFINE The DEFINE statement assigns symbol 
definitions for selected symbol names. 
If a selected symbol is already defined 
a duplicate symbol error occurs. 


DEFINE arguments are ‘<symbol> = 
<value>’, where <symbol> is the symbol 
to define and <value> is the definition. 
Definitions are input as absolute values 
(with or without a base address) or as 
plus/minus offsets to some other symbol. 


For absolute symbols, a colon separates 
the base and offset components of the 
address. If only one number is given, 

it is assumed to be the offset and the 
base address is set to zero. 


Example: To define ‘VERSION’ as 
‘3’, “51! as address ‘100 hex (base) 
and 10 binary (offset)' and 'S3' as 
“52 plus offset 5’: 


DEFINE VERSION = 3, S1 = 100:10B, S3 = S2+5 


Note: External symbol definitions in your 
program appear as addresses and 
not as values when you access them. 
For example, if you apply the 
assembly code 'MOV AX, VERSION’ 
to the preceding example, ‘AX’ 
receives the value of the word 
stored at ‘location 3’ and not the 
value ‘3’. 
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Change External Symbol Addressing 
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An obscure feature of the Intel format specifies the way ad- 
dresses are computed for certain references to external symbols 
in object files. The SYMGROUP and NOSYMGROUP statements 
select the way the Intel object format is handled by Plink86plus. 


STATEMENT STATEMENT Vp DEBCHIDIKOM ae ini Bate | 


=ч 


f SYMGROUP The SYMGROUP statement is the 

қ default for Plink86 р/и and is not 
required. This default is the opposite 
of some older versions of the 
Plink86p/us linkage editor. SYMGROUP 
is included here for compatibility with 
input files prepared for those versions. 


NOSYMGROUP The NOSYMGROUP statement changes 
the default method for computing 
addresses for certain references to 
external symbols in object files. 


Example: To load the link program , 
TEST.LNK with NOSYMGROUP 
activated: 


PLINK86 @TEST.LNK NOSYMGROUP «cr» 


NOSYMGROUP is only used when object 
files generated by Microsoft pre-version 
3.2 Pascal and Fortran compilers are 
linked. It must be used for Version 1 

of these compilers and must not be 
used with versions 3.2 or newer of 
these compilers. 


Е 
E 
3 
B 
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If Plink86p/us is not generating addresses correctly for your 
program, try saving the .EXE file and then run Plink86p/us again 
т with the NOSYMGROUP statement. 
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Symbol Table Conventions 


By default, Plink86p/us outputs part of the object's file name to 
the symbol table. The file name is stripped of drive, path and 
extension information. This is normally the most reliable informa- 
tion for source level debugging. The MTABLE statement overrides 
this default. 


STATEMENT DESCRIPTION 


MTABLE The MTABLE statement causes 
Plink86p/us to output object module 


names instead of file names. This could 
allow source level debugging capability 
when several languages are combined. 
However, Pfix86p/us does not currently 
support this format. 
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Microsoft Symbol Definition Notes 
i 


An oddity in symbol definitions for pre-version 3.3 Microsoft 
Pascal and Fortran compilers should be noted. As the application 
program begins execution, the run-time systems of these com- 
pilers move the data areas to a location that is impossible to 
determine at link time. However, if there is enough free memory 
for the run-time code to expand the static data area to 64kB, the 
final address can be predicted and Plink86p/us will output this 
address to the symbol table. Use the DSALLOC command to 
support this run time behavior. 


As a result, the symbol addresses for data symbols generated by 
these compilers will not be correct until after the run-time system 
has moved the data area, and even then it will not be right if there 
is insufficient memory left. However, the offset portion of the 
definition will be correct after the move. You can override the 
incorrect segment address by using Pfix86plus debugger input 
such as 'DS:XYZ' instead of just 'XYZ' to access a data symbol 
with that name. 
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CHAPTER 7 - REPORTS 


Overview 


This chapter describes memory map reports that Plink86p/us can 
create. 
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Generate Memory Map Reports 


Map reports describe the output of the linkage edit. They are 
useful for assembly language debugging and for planning how to 
organize the program components in memory. 


STATEMENT DESCRIPTION 


The MAP statement generates 
memory map reports. MAP with no 
arguments creates a MAP A 

‘All Segments’ report at the console. 


The syntax of the MAP statement is 


MAP [=<filename>][<flag>[, <flag>...]] 


If no extension is provided, Plink86p/us 
appends the extension .MAP. For example, 


MAP = TEST 


would create a MAP A report in the file 
TEST.MAP. 


<flag> arguments select the desired 
report or reports. Reports can show 
the memory addresses assigned by 
Plink86p/us to sections, segments and 
symbols in the linked program and 
also in the individual modules that 
were included in the linked program. 
MAP A is generated if no flag is 
given. 


Example: To create the global symbols 
(G) and modules (M) reports: 

MAP G, M 
To create the same reports in a file 
named TEST1.MOD: 


MAP = TEST1.MOD G, M 
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Map Flags 


MAP report flags are as follows: 


DESCRIPTION 


Global (Public) Symbols. 
Lists all public symbols of all loaded modules 
alphabetically with their assigned addresses. An 
asterisk is prepended to the name of each 
vectored symbol listed in the report. 


Sections. 
Lists all program sections alphabetically with their 
assigned disk, memory addresses and size. An 
asterisk is prepended to the name of each 
automatically-allocated segment listed in the 
report. 


All (Segments). 
Lists program sections in input order with 
segments of each section listed in order of 
ascending segment memory address, shown as a 
20-bit offset from the start of the program. If 

you call about a linkage problem, the technical 
support staff will probably want this report. 


Modules. 
Lists the modules in input order, with segments 
listed for each module and symbols listed for 
each segment. Common blocks and absolute 
symbols are listed separately. This is the largest 
report. An asterisk is prepended to the name of 
each vectored symbol listed in the report. An 
asterisk is also prepended to the name of each 
automatically—allocated segment listed in the 
report. 


Error Messages. 
Copies all console messages (except VERBOSE) 
and the Plink86 p/us termination message to the 
report. 


Each MAP report also includes the run-time memory require- 
ments of the program and a list of the libraries that were 
searched. If RELOAD is used, the size of the internal overlay 
loader stack is also listed. if CACHE is used, all cache requests 
are listed. 
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Section Report Headings 


MAP S column headings are as follows: 


DESCRIPTION 
Maddr: Memory address where the section will 
be loaded. 


Memory space used by the section. 


Address where the section is stored 
in a disk file. 


Disk space used by the section. 


Lev: Level number of this section (0 = 
permanently resident). 


Ovi: Overlay number of the section, where 
zero is the root section of the program 
that is loaded by the operating system. 
A non-zero indicates a section that will 

be loaded by the overlay loader. 


Overlay number of the section's 
ancestor section within overlay 
structure (0 = no ancestors). 


Preload flag. 'Yes' indicates a section 
that will be loaded by the overlay loader 
before program execution actually 
begins. 
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Merged Object File Maps 
EE a ктт 


When used during an object merge, MAP lists the modules, 
groups, segments and variables in the new file. Requests for 
section lists are ignored during the object merge. Variables can 
be one of four types: 


е EXTERNAL — Not defined by the merged object file. 

o PUBLIC — Global symbol. 

e PRIVATE - Previously public, now suppressed by 
PUBLIC. 

o PUB ABS - Public and absolute. 

o PRIV ABS - Previously public, absolute symbol, 
now private and absolute. 

o PUB DEF - User-defined public symbol. 

o PRIV DEF — User-defined private symbol. 
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Define Page Dimension Formats 


The WIDTH, HEIGHT and NWIDTH statements override defaults 
and produce customized column and page dimensions for MAP 
reports. 


STATEMENT| DESCRIPTION 


HEIGHT The HEIGHT statement changes the page 
height to the specified number of lines. 
Maps default to 65 lines per page if 
HEIGHT is not used. Plink86p/us outputs 
a form feed character to continue on 
the next page. 
Example: To change the number of lines 
in the MAP report to 80 per page: 

HEIGHT 80 


WIDTH The WIDTH statement sets the page width 
to the specified number of characters per 
line. Maps default to 80 characters per 
line when WIDTH is not used. 

Example: To set page width for MAP 
reports to 132 characters per line: 
WIDTH 132 

NWIDTH The NWIDTH statement changes the | 
width of symbol names and other identifiers | 
in the MAP report to the specified number | 
of characters. NWIDTH affects only the | 
reports, not the actual symbol names in | 
the files. Symbol names default to nine | 
characters in the MAP reports if NWIDTH ( 
іѕ пої иѕеа. | 
Example: To change symbol name width i 
on MAP reports to 18 characters: i 

NWIDTH 18 А 
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Sample Map Report 
[SS Ж ыы тыал» ЕН ЕК нын 


The memory map report on the next page was produced for the 
standard “PLTEST” program. This program is in the file 
PLTEST.EXE on the Plink86p/us distribution disk. 


The following input was used to generate this report: 


PLINK86 @PLTEST WIDTH 80 HEIGHT 10000 
MAP=PLTEST G,S, DEFINE PLTST1=0 


This links PLTEST and executes the statement input contained in 
that file. 


The map that is generated in this example is copied to a disk file 
(PLTEST.MAP). It includes the global symbols (G) and sections 
(S) reports. The HEIGHT and WIDTH statements set the page 
dimension formats. 


Segment names are given as the segment name followed by a 
period and the class name. For example, a segment named 
"HEAP" in class "MEMORY" would be named HEAP.MEMORY. If 
the compiler or assembler omits the class name, the literal ‘NIL’ 
is used. 


Note: MAP reports are always generated in the same order, 
regardless of the order the flags are given in the input. 
Also, the GROUP information is included in all map reports 
regardless of which flags are used. 
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Sample Map Report, Continued 
ee eS —ә 


After using the Pltest command, this output will be placed in a file 
named Pitest.tmp. 


Pilnk86plus 2.22. 
Memory Map for PLTEST.EXE 12/04/86 
Run Time Memory Requirements: 


Name bytes 
PLTEST.EXE 0x2570 or 10Kb 


Number of vectors: 0х8 (8) 


Groups: 


Name 
CGROUP 
DGROUP 


Symbols: 


FFS 


Address 
0 
2340 


Addr 


001с:02е8 
0003:0000 
001C:0348 
001C:077C 
001C:02e9 
0095:0001 
Бра араа 


VRO 95:0092 
SOVTABLES 0009:0000 
SROVERFLO 0095:016a 


"CROAK 
-PLTSTi 
"PLTST4 


Figure 7.1 
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Size 
2340 
30 


Name 


SLOADS 
SOVCLOSE 


SOVRSEGS 
ОУУС 


5 5 
SRUNDERFL 
PLT 


Addr 


001c:0287 
001C:007b 
001с:0778 
0095:00ас 
001c:067a 


0 : 

0095:0141 
0000:0000 
0000: 1384 
0000: 13a2 


г 
о 
< 


Onn en 


Name 
SNEEDDOS2 


Addr 


0095:0192 
0095:0000 
001c:048d 
001c:06ed 
001c:0349 
0018:0000 
0095:0094 
001c:044c 
0095:0088 
0000:0000 
0000:001b 
0000: 1137 


"PLTST6 0000:232e 


о 
< 
ox 
aj 
- 
3 


NONA UN 
оооооооо 


Sample Map Report 
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CHAPTER 8 - Plink86p/us EXAMPLES 


Overview 


This chapter provides examples that show how to link programs 
using C compilers and Microsoft Fortran and Pascal compilers. 
These examples provide an informal look at commonly-used 
Plink86p/us commands and linking techniques. 


Enough general information is provided here to handle a variety of 
applications. While the examples are written for the specific 
compilers listed above, much of the information presented here 
can also be applied to other compilers. 


Chapter Contents 


(———————————————————————— 


С. Examples esci fr cc Wr E LLL LE oos Bez 
Microsoft FORTRAN and Pascal Examples ............. 8-4 

n MÀ 
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C Examples 
a ——————— | 


Lattice C has two input requirements: 


ө C.OBJ (header file) must be linked first. 
ө LC.LIB (run-time support library) must be searched. 


This example is for Lattice C. If you are using a different C 
compiler, use the names of the startup object file and library 
appropriate to your compiler. Some compilers do not require you 
to explicitly specify the startup and library names. 


Non-Overlaid Lattice C Program 


OUTPUT TEST.EXE 
MAP z TEST.LST G 
FILE C, F1, F2, F3, F4 
LIBRARY LC 


Modules from C.OBJ and the other specified object files are 
linked here with required modules from LC.LIB in a program that 
is stored in the output file TEST.EXE. A memory map is gener- 
ated on disk in this example that lists all public symbol names and 
their addresses. 


Note: The library search only loads those modules from LC.LIB 
that défine symbols declared external but not defined in 
the already-linked modules. 


Lattice C Program with Overlays 


OUTPUT TEST.EXE 

MAP z TEST A 

FILE C, F1, F2, F3 

LIBRARY LC 

BEGINAREA SECTION FILE F4, F5 
SECTION FILE Fô, F7, ЕВ 
SECTION FILE F9 


ENDAREA 
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C Examples, Continued 
[ лгө. 


As in the previous example, modules from C.OBJ and the other 
specified object files are linked here with required modules from 
LC.LIB in a program that is stored in the output file TEST.EXE. 


In this example, the BEGINAREA and ENDAREA statements 
define an overlay area where three sections share the same 
memory space. 


There is another section at level zero, marked as overlay number 
four. This section contains all of the data areas for the program 
and is created automatically by Plink86p/us. Note that the 
LIBRARY statement is placed before the first BEGINAREA. Other- 
wise, Plink86p/us will place the code from the library modules into 
the current section in the overlay structure. If the LIBRARY 
statements are placed after the last ENDAREA, Plink86p/us will 
place the modules into the automatically created section at the 
end of the program. 


When this program is executed, MS-DOS loads only the root 
section containing C, F1, F2, F3, library routines and the overlay 
loader code. The overlay loader immediately loads the data 
overlay section. This section remains resident with the root 
section and overlay loader until the program is terminated. 


The data area is placed at the end of the program because the C 
run-time system starts the C heap at the end of the data area. 
Placing the data area at the end insures that the heap will grow 
into free memory. 


The memory map (option "A") generated in this example shows 
all segments in the link. The main section contains files F1, F2 
and F3. The three overlay sections are at level one. 


The link files for most other C compilers will follow the same basic 
format as that of Lattice C above. Some compilers, such as 
Microsoft C 3.0 and 4.0, place the startup code in a library 
module. 
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C Examples, Continued 


In some cases, the additional statement NODEFLIB may be 
added to suppress automatic library search requests. If 
Plink86p/us can not find the libraries, try NODEFLIB. Also, if 
Plink86p/us cannot resolve all symbols during the link, replace the 
LIBRARY statement with a SEARCH statement. 


The LIBRARY command instructs Plink86p/us to look through the 
library once. The SEARCH command instructs it to search until no 
more symbols can be resoived. 


Microsoft FORTRAN and Pascal Examples 


These examples assume Microsoft FORTRAN or Pascal version 
3.2x or older. FORTRAN is used in these examples, but the 
statements for Pascal are the same. 


With version 3.2 or older, Microsoft FORTRAN and Pascal compil- 
ers have two input requirements: 


o The FORTRAN.LIB or PASCAL.LIB library must be 
searched. Use the SEARCH command rather than the 
LIBRARY command. 


e Data segments must be allocated to high memory with 
the DSALLOC statement. Refer to the DSALLOC com- 
mand for a technical description. (With version 3.3 or 
newer of these Microsoft compilers, the DSALLOC state- 
ment is not required.) 


With version 3.2 of these Microsoft compilers, all com- | 
mon blocks must be defined in the block data module or 

in the main module. If they are defined elsewhere, they 

will be linked in the wrong place within the program and ( 
will probably crash upon execution. The MAP A report will 

reveal the locations of common blocks. 
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Microsoft FORTRAN and Pascal Examples, Continued 
—————— SSS eee 


Non-overlaid Microsoft FORTRAN & Pascal Program 


OUTPUT TEST.EXE 
MAP = TEST M 
DSALLOC 

FILE F1, F2, F3, F4 
SEARCH FORTRAN 


Modules from F1 and the other specified object files are linked 
here with required modules from the FORTRAN library in a 
program that is stored in the output file TEST.EXE. 


The MAP statement generates a list of all modules in the program 
and the segments contained in each module. The report is in the 
file TEST.MAP. Common block segments appear in a separate 
report. 


Microsoft FORTRAN & Pascal Program with Overlays 


OUTPUT TEST.EXE 

MAP = TEST A 

DSALLOC 

SECTION = ROOT 

FILE F1, F2, F3 

SEARCH FORTRAN 

BEGINAREA SECTION FILE F4, F5 
SECTION FILE F6, F7, F8 
SECTION FILE F9 

ENDAREA 

SECTION = DATA 


As in the previous example, modules from F1 and the other 
specified object files are linked here with required library modules 
in a program that is stored in the output file TEST.EXE. 


The BEGINAREA and ENDAREA commands define an overlay 
area where three sections share the same memory space. 
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Microsoft FORTRAN and Pascal Examples, Continued 
Pe ee ee | 


When overlays are used, Plink86p/us moves all data segments 
and common blocks to a section at the end of the program. The 
main portion of the program appears first, with the overlay 
sections sandwiched between the main section and the data 
section. 


At run-time, DOS loads only the root section and the overlay 
loader. The data section, which is marked for "pre-loading" by 
PlinkB6p/us, is then loaded immediately by the overlay loader 
before program execution begins. This is evident in the memory 
MAP A report listing all sections in the program. 


Note that the SEARCH statement appears before the first overlay 
area in this example. If SEARCH appeared within the 
BEGINAREA/ENDAREA, the code segments would be placed in 
that section. 


Of course overlay structures can be much more involved than 
these examples. Start out slowly, building the structure as you 
go. If at all possible, get the program running without overlays 
first, then incorporate the overlays. 
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CHAPTER 9 - COMMAND REFERENCE 


Overview 
Бы 


This chapter provides alphabetical references of all Plink86p/us 
commands, statements and utility programs. These functions 
have all been previously described in this manual. Information is 
summarized here for each item. 


Chapter Contents 


Syntax: Notation атта.” 9-4 
Statement Format Summary РИМК86................. 9-5 
Statement Abbreviations ........................... 9-5 
BLINKBO.EXE жыраға. cree cele tere CIT 9-6 
input Statement Summary .......................... 9-8 
ALLOCATE ....... 9-12 
ALWAYS ......... 9-14 
BATCH. enn 9-15 
BEGINAREA ....... 9-16 
САСНЕ 2222222. 9-18 
CLASS М... 9-22 
COMPATIBLE ..... 9-23 
DEBUG .. ;... 9-24 
DEFINE .......... 9-25 
DSALLOC ........ 9-27 
ENDAREA ........ 9-28 
FILE. со RENS 9-29 
GLOBAES ........ 9-31 
GROUP .......... 9-33 
HEIGHT 22222722 9-34 
LIBRARY ......... 9-35 
LOCALES... 55 9-36 


Chapter 9 - Command Reference Page 9-1 


Chapter Contents, Continued 
ШЕИ 


LOWERCASE ..... 9-38 
МАРСЕ. 9-39 
MAXBUFSIZE ..... 9-43 
MEMORY ......... 9-45 
MODULE ......... 9-46 
МТАВГЕ ......... 9-48 
NEVER tee ТІ, 9-49 
МОВЕ ТУ. 9-50 
NODEFLIB ........ 9—51 
NOLOCALS ....... 9-52 
NOPUBLICS ....... 9-53 
NOSYMGROUP .... 9-54 
NOTYPCHECK..... 9-55 
NOVECTOR ....... 9-56 
NWIDTHIOT T est. 9-57 
ОЦОТРИОТ ......... 9-58 
OVERLAY ........ 9-60 
PRELOAD ........ 9-61 
PUBLICERET м... 9-62 
RELOAD .....,.... 9-64 
SEARCH ......... 9-67 
SECTION ......... 9-68 
STACK ое... 9-70 
SYMGROUP ...... 9-71 
SYMTABLE ....... 9-72 
INIM rr. 9-74 
ТВАСК........... 9-75 
UPPERCASE ...... 9-77 
VERBOSE ........ 9-78 
WIDTH 222025... 9-79 
WORKFILE ....... 9-80 


Page 9-2 Plink86 plus User Manual 


Chapter Contents, Continued 


Utility’ Programs’ -. 2s 2: cet ee 2 erie eee eee 9-81 
CHECKSUM.EXE ... 9-82 
COMPARE.EXE .... 9-83 
DUMP.EXE ....... 9-84 
SYMTABLE.EXE ... 9-87 
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Syntax Notation Summary 


The following notation is used when statements and other com- 
mands are discussed here: 


NOTATION PURPOSE 


Items in CAPITAL letters must be input 
as shown or abbreviated as described 
in Chapter 3, “Command Formats.” 


Items in angle brackets < > should be 
optionally supplied by the user. 


Items in square brackets [ ] must be 
supplied by the user. 


Items followed by an ellipsis (...) can 
be repeated any number of times. 


Vertical bars indicate a choice between 
two or more entries. 


Indicates a carrige return, meaning 
press «ENTER». 
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Statement Format Summary PLINK86 


Plink86p/us command file and PLINK prompt input is free format. 
Statements can be extend any number of lines. Examples in this 
chapter are arranged in a block format for clarity. For example: 


OUTPUT  TEST.EXE 
FILE F1.0BJ 
BEGINAREA SECTION FILE F2.0BJ 
SECTION FILE F3.OBJ 


ENDAREA 
is the same as 


OUTPUT TEST FILE F1 BEGINAREA 
SECTION FILE F2 SECTION FILE F3 
ENDAREA 


Statement Abbreviations 


Statement key words may be abbreviated by dropping letters 
starting at the right-most character (FILE = FIL or Fl), so long as 
the abbreviation remains unique among all keywords. 


The previous example could also be entered as: 


OUT TEST FI F1 
BEGIN SEC FI F2 
SEC FI F3 END 
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PLINK86.EXE 
SS A EE EE NR A -галылы с-түн ЕЕЕ; ЕСПЕ ЫШЫ ОЗ — ------- 
ТАЕ АНЕ 
Туре: 

Plink86p/us Linkage Editor Program 


Purpose: 
Executes Plink86p/us to begin the linkage edit. 


Syntax: 
PLINK86 «statements» «cr» 


Background: 
The file PLINK86.EXE is required to execute this program. 


Input: 
Plink86p/us сап be executed in three different ways: 


ә interactively where the program prompts for statement 
input. 


e With statement input included in the command line. 
e With statement input inserted from a separate disk file. 


For interactive input, a semi-colon character ; indicates the end 
of input. 


For statement input from a disk file, the character '(?' precedes 
the file name to use as command input. 
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PLINK86.EXE, Continued 


Examples: 
PLINK86 «cr» 


Executes Plink86p/us for interactive input. 
PLINKB86 file test verbose «cr» 


Executes Plink86p/us, links the file TEST.OBJ creating a file 
TEST.EXE and activating the VERBOSE function. 
PLINK86 @test.Ink «cr» 


Executes Plink86p/us with statement input from the file TEST.LNK. 
In this example, assume TEST.LNK contains the following: 


output test. ехе 
file test.ob] 

lib math. lib 
map = test 


Plink86p/us will execute with the contents of TEST.LNK used as 
the command input. : 
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=== 


Input Statement Summary 


Input statements define and manage the program linkage 
process. 


STATEMENT PURPOSE 


ALLOCATE Automatically allocates library modules 
to the overlay structure as required. 


ALWAYS Forces use of the symbol vector 
address for references to a specified 
symbol. 


BATCH Causes Plink86p/us to terminate if it 
cannot find a requested file. 


Creates an overlay area starting at 
the current memory allocation 
address. 


CACHE Creates an overlay cache in available 
DOS memory, extended memory, or 
expanded memory. 


CLASS Moves segments in a class to the 
current section. 


BEGINAREA 


COMPATIBLE Changes the comment marker from 

'#' to '9&' for compatibility with link files 
generated for earlier versions of 
Plink86p/us and Plink86. 


DEBUG Identifies each overlay at the console 
as it is loaded during program 
execution. 


DEFINE Resolves external symbol references 
by assigning a value if the symbol is 
not defined by any module in the 
program. 
DSALLOC Changes the address of the group 
DGROUP to be the size of the group 
minus 10000H. 


Identifies the end of an overlay area. 


ENDAREA 
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Input Statement Summary, Continued 


STATEMENT PURPOSE 


FILE Defines object files for linkage input. 


GLOBALS Selects public symbols to include in the 
symbol table. 


Moves all segments within the specified 
groups into the current section. 


HEIGHT Sets map report number of lines per 
page. 


LIBRARY Defines libraries for linkage input and 
searches them once for symbols. 


LOCALS Specifies modules whose local symbols 
are desired in the symbol table. 


LOWERCASE Translates all symbol names апа 
identifiers to lower case. 


Generates memory map reports that 
describe the linkage edit output. 


Forces DOS to use its own I/O buffers 
by limiting the size of the I/O opera- 
tions Plink86p/us will perform. 


MEMORY Specifies the maximum memory space 
to allocate beyond the memory 
required to load the program, overlays 
and data areas. 


MODULE Assigns all segments from the specified 
modules to the current section. 


mE 
| 
ы 
pn 
H 
“ 


MTABLE Outputs stripped object module names 
to the symbol table instead of the 
default file names. 


CONTINUED 
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Input Statement Summary, Continued 
SE 11.27.7001 


STATEMENT PURPOSE 


NEVER Forces the use of the real address 
and never the symbol vector address 
for references to specified symbols. 

NOBELL Suppresses beeps associated with 
Plink86 plus messages. 

NODEFLIB Suppresses automatic library search 
requests. 

NOLOCALS Eliminates all local symbols and line 
numbers from the symbol table. 

NOPUBLICS Specifies symbols that are not 
globally accessible after an object 
file merge. 

NOSYMGROUP Changes how addresses are computed 
for certain external symbol references 
in object files. 

NOTYPCHECK Disables TYPDEF record processing as 
required for linking large programs 
compiled with the Intel PL/M or 
Microtech Research Professional 
Pascal compilers. 

NOVECTOR Effectively sets the NEVER statement 
for all variables in specified files only, 
prohibiting Plink86 plus from vectoring 
any of those symbols. 

NWIDTH Sets the column width for symbol 
names and other identifiers on map 
reports. 


OUTPUT Creates an .EXE file to hold a linked 
program, or an .OBJ file to hold a 
merged object module. 

OVERLAY Specifies segment classes that can 
remain in the overlay structure. 


CONTINUED 
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Input Statement Summary, Continued 


STATEMENT PURPOSE 


PRELOAD 


Loads a specified overlay section into 
memory before passing control to the 
user program. 


PUBLIC Designates the only public symbols 


available in a merged object file. 


RELOAD Reloads overwritten overlays auto- 
matically as required by the program. 

SEARCH Defines libraries for linkage input and 
searches them repeatedly for un- 
defined symbol definitions. 

SECTION Creates a program section that is 
loaded from disk as a separate unit 
or (SECTION INTO) places an overlay 
into a separate disk file. 


STACK Changes .EXE file header stack size. 

SYMGROUP Selects the way the Intel 8086 object 
format is handled by Plink86p/us. 

SYMTABLE Generates a symbol table for use with 
the Pfix86 plus symbolic debugger. 

TINY Strips debugging information from 
merged object files. 

TRACK Enables automatic overlay reloading 


for selected symbols only. 
UPPERCASE Translates all symbol names and 
VERBOSE 


identifiers to upper case. 
WIDTH 


Displays a status line at the console. 
WORKFILE 


Each of these statements is described in detail in this chapter. 


Sets page width for map reports 
(default: 80). 


Specifies a file name other than the 
default PLINK86. WRK and optionally 
a drive and path for the Plink86 p/us 
temporary work file. 
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ALLOCATE 


Type: 
Plink86p/us Statement Key Word 


Purpose: 


Automatically allocates library modules to the overlay structure. 


Syntax: 
ALLOCATE <library>[, <library>, ...] 


Background: 


ALLOCATE places modules from specified libraries into the 
overlay structure at locations where they are needed, eliminating 
the need for linking “all selected library modules” into the root of 
the overlay structure. Segments are placed in the overlay with the 
highest possible level number. This overlay must be an ancestor 
of all overlays it is called by. 


However, ALLOCATE will only work for self-contained modules 
that do not make calls to overlays. This is because overlay calls 
may not be properly vectored. The ALWAYS statement can force 
vectoring for individual symbols, but is not practical for large 
applications. 


Note: 


When the VERBOSE statement is used with ALLOCATE, 
Plink86p/us displays the message “Module allocation: Segment x 
Module y in Section z." All segments that are assigned by 
Plink86p/us to sections other than the root are listed. 
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ALLOCATE, Continued 
oe c MR URN NNNM 


Input: 


ALLOCATE is followed by the «library» name or names whose 
modules are automatically allocated to the overlay structure. 
«library» arguments are separated by a comma and a space. 


Microsoft C Note: 


ALLOCATE may not work properly on Microsoft C applications 
because the run-time libraries mix near and far calls and ALLO- 
CATE might inadvertently place modules more than 64kB apart. If 
a near call cannot be vectored, the module that refers to it must 
be moved to within 64kB of the start of the overlay table. 


Examples: 
ALLOCATE lib1, lib2, lib3 


Identifies LIB1, LIB2 and LIB3 as being available for automatic 
module allocation to the overlay structure. 


ALLOCATE lib1, lib2, lib3 
verbose 


Identifies LIB1, LIB2 and LIB3 as being available for automatic 
module allocation to the overlay structure and also displays the 
names of segments that are assigned by Plink86p/us to sections 
other than the root. 
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Plink86p/us Statement Key Word 


Purpose: 


Forces the overlay structure to always use the symbol vector 
address when referencing a specified symbol. 


Syntax: 
ALWAYS <symbol>[, <symbol>, ...] 


Background: 
ALWAYS causes Plink86p/us to override its default method for 
automatically accessing overlays. Normally, when an address in 
Section A is a reference to a symbol in Section B, Plink86p/us 
automatically substitutes the symbol vector address for the real 
address, except when Section A is a descendant of Section B. 


ALWAYS causes Plink86p/us to always substitute the symbol 
vector address for the real address when reference is made to 
the specified symbol or symbols, regardless of ancestor/descen- 
dant relationships. 


Input: 
ALWAYS is followed by the <symbol> name or names to always 
use the symbol vector address for <symbol> arguments must be 
separated by a comma. 


Example: 
ALWAYS SIN, COS, TAN 


Instructs Plink86p/us to always use the symbol vector address 
instead of the real address for external references to symbols 
named SIN, COS and TAN. 
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BATCH 
А.а ЬЕ 


Туре: 
Plink86p/us Statement Key Word 


Purpose: 


Causes Plink86p/us to terminate with a fatal error if it cannot find 
a requested object file or library. 


Syntax: 
BATCH 


Background: 


Normally, Plink86p/us prompts the operator to enter the name of 
a disk drive or directory path name if it cannot find a requested 
object file or library. 


BATCH causes Plink86p/us to terminate instead. This is useful if 
the program is being run from within a batch file and no operator 
is available to respond to the prompt. 


Input: 
BATCH has no arguments. 


Example: 
BATCH 


Instructs Plink86p/us to terminate if it cannot find any of the files 
specified in FILE, LIBRARY, or SEARCH statements, or in an 
automatic library search request. 
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BEGINAREA 
a чс en 3 


Type: 
Plink86p/us Statement Key Word 


Purpose: 


Creates an overlay area beginning at the current memory alloca- 
tion address. 


Syntax: 
BEGINAREA 


Background: 


Overlay areas are created with the BEGINAREA and ENDAREA 
statements. Each overlay area must begin with a BEGINAREA 
statement and end with an ENDAREA statement. Any sections 
created between these two paired statements automatically be- 
come overlays. BEGINAREA/ENDAREA statements may be nested 
to form more complex overlay structures. 


Input: 
BEGINAREA has no arguments. 
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BEGINAREA, Continued 
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Example: 
output test 
file f1 
BEGINAREA 


section file f2 

section file f3 

section file f4 
endarea 


Creates a program TEST.EXE consisting of four sections. F1 is 
the root, which is always resident in memory. F2, F3 and F4 are 
overlays because they appear within the BEGINAREA and EN- 
DAREA statements. These overlays share the same address in 
memory and are loaded by the overlay loader, which resides in 
the root section. 
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CACHE 


Type: 
Plink86p/us Statement Key Word 


Purpose: 


Creates an overlay cache in available DOS memory or in ex- 
tended or expanded memory. 


Syntax: 


CACHE REGULAR <maximum cache size> 
[,<minimum program size>] 

CACHE EXTENDED <maximum cache size> 
[,<minimum program size>] 

CACHE LIM <maximum cache size> 
[,<minimum program size>] 


Background: 


CACHE requests an overlay loader that determines the available 
memory and uses a portion of it as an overlay cache. Overlays 
are then loaded into the reserved area of memory before they 
are overwritten during the run, eliminating the need for reloading 
them from disk during program operation. The cache will not 
overwrite memory which has previously been allocated and will 
not grow larger than the total size of all non-resident overlays. 
When the program has finished executing, the cache area is 
returned to available memory. 


Overlay caching allows programs to contain an overlay structure 
designed for a small-memory PC-type computer that will execute 
faster on larger-memory PC/AT-type computers. When the pro- 
gram is executed on the smaller machine, overlays are loaded 
from disk when required for execution. If the same program is 
executed on the larger machine, overlays can be loaded to the 
cache area when the program is executed and then moved to the 
correct memory address when required. 
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CACHE, Continued 


CACHE arguments specify if the memory cache is created in 
regular DOS memory, in extended (80286 protected mode) 
memory, or in expanded LIM  (Lotus-Intel-Microsoft bank- 
switched) memory. In all three cases, the cache will not overwrite 
memory which has previously been allocated. 


If the target computer has the requested memory type available, 
the cache is created. If not, execution continues as it would 
without the CACHE statement. Multiple CACHE statements can 
make an application program capable of using any of the three 
cache types as it encounters different hardware configurations. 


When multiple CACHE statements are used, Plink86p/us looks 
first for LIM expanded memory. If expanded memory is not 
present (or if it contains insufficient memory for the cache), 
Plink86p/us looks for extended memory. If extended memory is 
not available, PlinkB6p/us looks for DOS regular memory for the 
cache. If there is insufficient DOS memory available, no cache is 
created. 


Input: 


CACHE is followed by the cache type. REGULAR is assumed if 
none are specified. 


Cache types are as follows: 


REGULAR Regular DOS memory. 
EXTENDED Extended 80286 protected mode. 
LIM Expanded Lotus-Intel-Microsoft bank 


switched memory. 


Only one cache type can be specified per CACHE statement, but 
more than one CACHE statement can be used in the input. 
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CACHE, Continued 
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<maximum cache size> specifies the maximum amount of mem- 
ory the cache can absorb. <minimum program size> optionally 
specifies the minimum amount of extra memory required for the 
program beyond the amount required to load it, insuring that the 
cache leaves enough extra memory for the program to function. 


Cache size and program size parameters can be input as 16-byte 
hex paragraphs (the default), as decimal kilobytes ('k' or 'К'), or 
as a decimal percentage of available free memory ('%'). For 
example, '100' is 100 hex paragraphs,'100k' is 100kB decimal, 
and ‘100%’ is 100 percent decimal. Percent can also be entered 
as 'p100' for compatibility with earlier versions of Plink86p/us. 


ECACHE Note: 


CACHE EXTENDED is the same as the ECACHE statement in 
earlier versions of PlinkB6p/us. ECACHE is included for compati- 
bility with these earlier versions, but future PlinkB6p/us releases 
may not support the ECACHE statement. Use CACHE EXTENDED 
instead. 


Note: 


Programs that fork child processes may return the cache mem- 
огу to DOS by calling the OVERLAY.LIB procedure $OVCOFF 
before forking. Programs that terminate and stay resident may 
attempt to use caching by calling $OVCOFF before terminating 
and then calling $OVCON upon activation. Use far calls for 
$OVCON and $OVCOFF. 
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Examples: 


CACHE 100%, 500 


Creates an overlay cache that can use up to 100% of the 
available regular DOS memory after reserving 500 hex para- 
graphs for program functions. The cache will never grow larger 
than the total size of all overlays. 


CACHE regular 50%, 50% 
CACHE extended 100% 
CACHE lim 1024k, 256k 


Depending on the target computer’s configuration, creates a 
cache in regular memory, in extended memory, or in expanded 


LIM memory. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 
Moves all segments in a class to the current section. 


Syntax: 
CLASS <classname> [(<segment>[, ... <segment>)]] 


Background: 
CLASS is not required for normal operation. It overrides all other 
specifications and changes the program's canonic segment 


ordering. 


Input: 
CLASS is followed by the «classname» to move. All segments in 
the specified class (including private segments) are moved to the 
current section. 


Options 
(«segment») identifies the order of the segments within the given 
class. All segments of the class are moved to the current 
section. («segment») arguments are separated by a comma and 
a space. The entire list of segments is enclosed in parenthesis. 


Examples: 
CLASS MEMORY 


Moves all segments in the class MEMORY to the current section. 
CLASS DATA (OV1DATA, OV2DATA) 


Moves only OV1DATA and OV2DATA from the class DATA to the 
current section. 
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COMPATIBLE 
Шш л eee 
Туре: 

Plink86p/us Statement Key Word 


Purpose: 


Changes the comment marker from ‘#’ to "“%” for compatibility 
with link files generated by earlier versions of Plink86p/us and 
Plink86. 


Syntax: 
COMPATIBLE 


Background: 


Earlier versions of Plink86p/us and PlinkB6 used the percentage 
sign ‘%' to indicate comment text in the statement input. The 
pound sign '#”' is now used to indicate comment text. COMPAT- 
IBLE causes Plink86p/us to recognize the percentage sign '96' 
and not the pound sign ‘#’ as the comment marker. 


Input: 
COMPATIBLE has no arguments. 


Example: 
plink86 COMPATIBLE @test.Ink «cr» 


Causes Plink86p/us to recognize '%' instead of ‘#’ as the com- 
ment marker while processing statement input from TEST.LNK. 
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Plink86p/us Statement Key Word 


Purpose: 
I 
Identifies each overlay as it is loaded during program execution. 


Syntax: 
DEBUG 


Background: 


DEBUG selects the debugging version of the overlay loader. This 
loader displays a message that identifies the overlay as it is 


loaded. 


DEBUG provides a convenient method for testing and debugging 
overlays. With a link map and DEBUG, you can follow the overlay 
process at each step while the program executes. 


Input: 
DEBUG has no arguments. 


Example: 


plink86 DEBUG @test.Ink «cr» 


Loads Plink86p/us with input inserted from TEST.LNK. The debug- 
ging version of the overlay loader is used. When TEST.EXE is 
executed, each overlay is identified at the console as it loads. 
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DEFINE 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Resolves references to external symbols by assigning a value to 
them. 


Syntax: 
DEFINE «symbol» - «value» 


Background: 


An "Undefined symbols exist" error message is issued when 
references are made to a symbol that is not defined by any 
module in the program. DEFINE fixes these references by assign- 
ing a value. 


Input: 
DEFINE is followed by the «symbol» to define and its assigned 
«value». Definitions can be input as absolute values (with or 
without a base address) or as plus/minus offsets to some other 
symbol. For absolute symbols, a colon separates the base and 
offset components of the address. If only one number is given, it 
is assumed to be the offset and the base address is set to zero. 


Note: 
External symbol definitions in your program appear as addresses 
and not as values when you access them. For example, the 
assembly code ‘MOV AX, VERSION' applied to the example below 
results in 'AX' receiving the value of the word stored at location 
:3' and not the value ‘3’. 
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DEFINE, Continued 
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Example: 
DEFINE VERSION = 3, S1 = 100:10, S3 = S2+5 


Defines ‘VERSION’ as ‘3’, 'S1' as ‘address 100 hex (base) and 
10 hex (offset) and "53" as 'S2' plus offset ‘5’. 
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DSALLOC 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Changes the address of the group DGROUP to be the size of the 
group minus 10000H. 


Syntax: 
DSALLOC 


Background: 


DSALLOC must be used with Microsoft Fortran and Pascal ver- 
sions 3.2 or below. It is not required for programs linked under 
version 3.3 of these compilers. 


With DSALLOC, all items referenced relative to DGROUP will have 
offsets as though DGROUP were moved to the high end of the 
physical segment that holds the data area. At execution time, the 
run-time systems of the Microsoft Fortran and Pascal compilers 
move the DGROUP segments to a higher memory address before 
any references to them are made. 


Input: 
DSALLOC has no arguments. 


Example: 


output test.exe 
DSALLOC 

file f1, f2 

library fortran.lib 


Links the object files and library file in the output file and allocates 
the DGROUP data segments to a higher memory address. 


Chapter 9 - Command Reference Page 9-27 


ENDAREA 
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Туре: 
Plink86p/us Statement Key Word 


Purpose: 


Identifies the end of an overlay area. 


Syntax: 
ENDAREA 


Background: 


Overlay areas are created with the BEGINAREA and ENDAREA 
Statements. Each overlay area must begin with a BEGINAREA 
statement and end with an ENDAREA statement. Any sections 
created between these two paired statements automatically be- 
come overlays. These statements may be nested to create more 
complex overlay structures. 


Input: 
ENDAREA has no arguments. 


Example: 
output · test 
file f1 
beginarea 


section file f2 

section file f3 

section file f4 
ENDAREA 


Creates a program TEST.EXE consisting of four sections. F1 is 
the root, which is always resident in memory. F2, F3 and F4 are 
overlays because they appear within the BEGINAREA and EN- 
DAREA statements. These overlays share the same address in 
memory and are loaded by the overlay loader, which resides in 
the root section. 
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FILE 
кышы Eee 


Type: 
PlinkB6plus Statement Key Word 


Purpose: 
Defines object files for input to the linkage edit. 


Syntax: 


FILE «filename»[, «filename», ...] 


Background: 


At least one FILE statement is required in the Plink86p/us com- 
mand input to define the files to link. All modules contained in 
object files listed as arguments in the FILE statement are included 
in the output program. 


Input: 
FILE is followed by the «filename» of the file or files to link. 
«filename» arguments are separated by a comma and a space. 
File type defaults to .OBJ if not specified. 


Note: 
If an object file requested by the FILE statement cannot be found, 
Plink86p/us checks for a DOS environment string named ‘OBJ’. 
Typically, this string is set up to refer to a directory that contains 
libraries and other commonly used object files that are available 
for linking. 


The value of this string is assumed to be one or more directory 
path names in the standard DOS PATH command format. 
Рііпк86р/иѕ prepends the path names to the requested object file 
name, adds the separator character 'N' between the path name 
and file name, and searches again for the file. 
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FILE, Continued 
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For example, if SET OBJ=\OBJECT is entered before Plink86p/us 
is executed and the file TEST.OBJ is being searched for, 
PlinkB6plus looks for NOBJECTNTEST.OBJ. If the input file still 
cannot be found, Plink86p/us prompts for entry of a path name to 
prepend to the requested file name and searches again. This also 
occurs if no suitable DOS OBJ string exists. 


Examples: 
FILE test.obj 


Identifies TEST.OBJ as an input object file whose modules will be 
linked in the output file. 


FILE a, b 


Identifies A.OBJ and B.OBJ, as input object files whose modules 
will be linked in the output file. 
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GLOBALS 
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Туре: 
Plink86p/us Statement Key Word 


Purpose: 


Includes selected global (public) symbols only in the symbol 
table. This is useful for large applications where the symbol table 
becomes too large for Pfix86p/us or Pfinish to handle. 


Syntax: 


GLOBALS FILE «filename»[, «filename», ...] 
GLOBALS MODULE «modulename»[, «modulename», ...] 
GLOBALS SYMBOL «symbolname»[, «symbolname», ...] 


Background: 


By default, Plink86p/us includes all global symbols in the symbol 
table. GLOBALS overrides this to include selected globals only. 
The GLOBALS symbol automatically suppresses local symbols. 
Use GLOBALS to include local symbols. 


Input: 


GLOBALS is folowed by the «filename», «modulename» or 
<symbolname> to include global symbols from. Arguments are 
separated by a comma and a space. Three separate statements 
are required to specify files, modules and symbols. 


Options: 
FILE includes public symbols from the specified files only. 


MODULE includes public symbols from the specified modules 
only. 


SYMBOL includes the specified global public symbols only. 
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GLOBALS, Continued 


Example: 


output test.exe file f1, f2 
library LIB1, LIB2 symtable 
GLOBALS file lib1.lib 
GLOBALS module F1 
GLOBALS symbol COS 


Appends a symbol table to TEST.EXE that includes all public 
symbols from the file LIB1 and from the module F1. All public 
symbols in F2 and LIB2 are excluded except COS. 


| 
2 
a 
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GROUP 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 
Moves all segments within the specified groups into the current 


section. 


Syntax: 
GROUP <groupname>[, <groupname>, ...] 


Background: 
GROUP is an override command and is not needed for normal 


PLINK86 operation. 


Input: 

GROUP is followed by the «groupname- of the group or groups to 

allocate to the current section. «groupname» arguments are 
separated by a comma and a space. 

Note: 

GROUP overrides all section assignments issued with the FILE, 

LIBRARY and SEARCH statements. It does not override the 

MODULE or CLASS statements. 


Example: 
GROUP DGROUP, COMGRP 


Allocates DGROUP and COMGRP to the current section. 
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HEIGHT 
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Type: 

Plink86p/us Statement Key Word 


Purpose: 
Changes the page height of the memory map reports to the 
specified number of lines. 

Syntax: 
HEIGHT <number of lines> 


Background: 
MAP reports default to 65 lines per page when HEIGHT is not 
used. 


Plink86p/us outputs a form-feed character when a report is to 
continue printing on the next page. The default radix is decimal. 


Input: 
HEIGHT is followed by the <number of lines> to set per page. 


Example: 
HEIGHT 80 


Changes the number of lines to 80 per page for memory map 
reports. 
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LIBRARY 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Defines libraries for input to the linkage edit. 


Syntax: 
LIBRARY <libraryname>[, <libraryname>, ...] 


Background: 
LIBRARY is commonly used to input the run-time support librar- 
ies included with most compilers. LIBRARY selects only the 
library modules that define symbols that were previously declared 
external and are currently undefined in the already-linked mod- 
ules. The selected library modules resolve external symbol refer- 
ences in the linked input object files. 


This selective culling of the library file is called a library search. 
Program size is reduced by this search method because it only 
loads the portions of the run-time support that are needed. 


Input: 


LIBRARY is followed by the «libraryname» of the library file or 
library files to search. «libraryname» arguments are separated by 
a comma and a space. .LIB is the default file type unless 
otherwise specified. 


Example: 
LIBRARY A.LIB, B.LIB 


Identifies A.LIB and B.LIB as input library files whose modules can 
be linked in the output file. 
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Type: 
Plink86p/ius Statement Key Word 


Purpose: 


Specifies individual modules whose local symbols are desired in 
the symbol table. 


Syntax: 
LOCALS <modulename>[, <modulename>, ...] 


Background: 


Under normal operation, the SYMTABLE statement loads all 
symbols in all modules of the input files into the symbol table. 
LOCALS causes local symbols to be loaded only from the 
specified modules. This is useful for linking large programs where 
the. symbo! table might become too large for the Pfix86p/us 
debugger (i.e., LOCALS can retain local symbols for only the 
modules being debugged). 


Input: 
LOCALS is followed by the <modulename> of the module or 
modules whose local symbols are allowed in the symbol table. 
«modulename» arguments are separated by a comma and a 
space. 


Note: 


Alternatively, the NOLOCALS statement can eliminate all local 
symbols from the symbol! table and the GLOBALS statement can 
include selected global symbols only or globals from selected 
files or modules only. 
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LOCALS, Continued 


Example: 


output test.exe 
symtable 

file f1 

LOCALS SIN, COS, TAN 


Excludes local symbols and line numbers from the symbol table 
generated from F1 and appended to the end of TEST.EXE, but 
includes local symbols from modules named SIN, COS and TAN. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Forces PlinkB6p/us to translate all identifiers and symbols to lower 
case. 


Syntax: 
LOWERCASE 


Background: 


By default Plink86p/us uses the original upper or lower case freely 
mixed for all identifiers and symbol names. LOWERCASE over- 
rides this default and forces all identifiers and symbol names to 
lower case. 


Input 
LOWERCASE has no arguments. 


Example: 
plink86 LOWERCASE @test.Ink «cr» 


Loads Plink86p/us with input inserted from TEST.LNK and con- 
verts all identifiers and symbols to lower case in the linked 
program. 


Page 9-38 Pilnk86 plus User Manual 


MAP 
ee 


Type: 
Plink86p/us Statement Key Word 


Purpose: 


Generates memory map reports that describe the linkage edit or 
the output of a file merge. 


Syntax: 
MAP [= <filename>] [<flag>, <flag>, ...] 


Background: 


MAP is useful for assembly language debugging, for memory 
management planning and for linkage edit testing and debugging. 


Reports can show the memory addresses assigned by Plink86p/us 
to sections, segments and symbols in the linked program and in 
the modules that were included in the linked program. 


Each report also includes the run-time memory requirements of 
the program and a list of the libraries that were searched. If the 
RELOAD statement is used, the size of the internal loader stack is 
also listed. If CACHE is used, all cache requests are listed. 


Input: 
MAP with no arguments generates a MAP A "All segments" 
report at the console. 


Options: 
[= «filename»] generates the report in the specified disk file 
instead of at the console. If file type is not specified, PlinkB6p/us 
adds the file type .MAP automatically. 


[<flag>] arguments select the report or reports to generate. 
«flag» arguments are separated by a comma and a space. MAP 
A is produced automatically if no flags are specified. 
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MAP, Continued 


MAP flags are as follows: 


DESCRIPTION 
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ALL (Segments). 

Lists program sections in input order with 
segments of each section listed in order 
of ascending memory address. 


Segment names are given as the segment 
name followed by a period and the class 
name. For example, a segment named 
‘HEAP’ in class ‘MEMORY’ would be 
named 'HEAP.MEMORY'. If the compiler 
or assembler omits the class name, the 
literal 'NIL' is used. Each segment name 
is followed by the segment memory 
address shown as a 20-bit offset om 

the start of the program. 


Error Messages. 
Lists all console messages (except 


VERBOSE) and the Plink86p/us termination 
message. 


Global (Public) Symbols. 

Lists all public symbols of all loaded 
modules alphabetically with their assigned 
addresses. An asterisk is prepended to the 
name of each vectored symbol listed in the 
report. 


Modules. 

Lists modules in input order, with 

segments listed for each module and 
symbols listed for each segment. 

Common blocks and absolute symbols are 
listed separately. An asterisk is prepended 
to the name of each vectored symbol and 
to the name of each automatically—allocated 
segment listed in the report. Uninitialized 
segments are also identified. 


CONTINUED 
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FLAG DESCRIPTION 


Sections. 

Lists all program sections alphabetically with 
their assigned disk, memory addresses and size. 
An asterisk is prepended to the name of each 
automatically allocated segment listed in the 
report. 


MAP S section report column headings include: 


Column Description 


Memory address where the 
section will be loaded. 


Memory space used by the 
section. 


Address where the section 
is stored in a disk file. 


Disk space used by the 
section. 


Level number of this 
section (0 = non-overlay). 


Overlay number of the 
section of the program 
loaded by the operating 
system. A non-zero 
indicates a section for the 
overlay loader to load. 


Overlay number of the 
section's ancestor section 
within the overlay structure 
(0 = no ancestors). 


Pload: Preload flag. ‘Yes’ indicates 
a section that will be loaded 
by the overlay loader before 


program execution begins. 
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MAP, Continued 


Object merge: When MAP is used during an object file merge, 
the report lists the modules, groups, segments, and variables in 
the merged file. Requests for a Section list are ignored. 


Variables can be any of seven types: 


TYPE DESCRIPTION 
esa -| Not defined by the merged object file. 


Includes only specified public symbols in 
object files that are merged into a new 
object file. 
Pub Abs Public and absolute 
Private and absolute. 
Pub Def Public symbol user-defined. 


Priv Def Private symbol user-defined. 


Previously public symbol definition was 
suppressed with the PUBLIC statement. 


Cache Note: 


All cache requests are reported in a table on the MAP report. This 
table lists for each of the three cache memory types, the amount 
of memory requested for the cache and reserved for the applica- 
tion. 
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Format Note: 


The WIDTH, HEIGHT and NWIDTH statements produce 
customized column and page dimensions for MAP reports. 


Examples: 
output test.exe file f1.obj, f2.0bj MAP = ргов1 s 


Generates MAP S (sections report) for the file TEST.EXE and 
stores it in a disk file named PROG1.MAP. 


output test.obj file f1.obj, f2.0bj MAP 


Generates a map report to the console for the merged output file 
TEST.OBJ listing modules, groups, segments, and variables. 
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Type: 
Plink86p/lus Statement Key Word 


Purpose: 


Forces DOS to use its own І/О buffers by limiting the size of the 
М/О operations PlinkB6p/us will perform. 


Syntax: 
MAXBUFSIZE «number of bytes» 


Background: 


DOS attempts to optimize certain |/O operations by executing 
them directly to or from the PlinkB6p/us I/O buffers, which can be 
2kB or more, depending on the disk block size. Unfortunately, 
some memory option cards aren't fast enough for some 1/О 
operations because DMA transfers the information to or from the 
hard disk. If the card isn't fast enough, DMA transfers FF or 00 
bytes instead of the correct data or it corrupts other data 
elsewhere on the card. 


MAXBUFSIZE provides a solution for this problem by limiting the 
size of the I/O operation PlinkB6p/us will perform. This forces DOS 
to use its own internal buffers for the operation. These buffers 
reside on the system memory board and are accessed correctly. 


Input: 


MAXBUFSIZE is followed by the hexadecimal «number of bytes» 
Plink86p/us can use for I/O operations. 


Example: 
MAXBUFSIZE 200 


Limits Plink86p/us 1/О operations to 200 hex bytes. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 
Specifies the maximum amount of memory to be allocated in 
addition to the memory required to load the program (including 
overlays and data areas). This statement replaces the HIGH 
statement found in earlier versions of Plink86p/us. 


Syntax: 
MEMORY «number of paragraphs» 


Background: 
MEMORY allows Plink86p/us to use the memory management 
features provided by DOS version 2.x. Under normal operation, 
PlinkB6p/us allocates all free memory to a program when it is 
executed. The MEMORY statement specifies in 16-byte hex 
paragraphs how much extra memory to allocate for the program. 
Remaining unallocated memory is then available for assignment 
by DOS version 2.x memory calls. 


Input: 
MEMORY is followed by the «number of paragraphs» to allocate 
in addition to the memory required to load the program. The hex 
paragraph value supplied here is added to the value written at 
offset OAH (minimum extra memory needed) and then written to 
the .EXE file header at offset OCH. 


Example: 
MEMORY 1000 


Specifies a maximum of 1000 (hex) paragraphs of extra memory 
(64kB). 
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Type: 
PlinkB6p/us Statement Key Word 


Purpose: 


Assigns segments from the specified modules to the current 
section. 


Syntax: 
MODULE <modulename>[, «modulename», ...] 


Background: 


MODULE overrides the FILE, LIBRARY and SEARCH statements. 
It does not override the CLASS statement or the canonic class 
ordering. MODULE is most useful when applied to select modules 
from within a library. For example, selected library modules may 
be put into an overlay while the rest of the modules remain 
resident in the program. 


Input: 


MODULE is followed by the «modulename» of the module or 
modules containing segments to assign to the overlayable current 
section. 


Note: 


Determining module names can be tricky and depends on the 
compiler. FORTRAN compilers typically set the module name as 
specified by the programmer, but some compilers give each 
module the same name, making the MODULE statement imprac- 
tical. 
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Example: 


section library fortran.lib 
section MODULE ENTX6L 


Assigns all modules from the FORTRAN library to the first section 
except for segments in the module ENTX6L, which are assigned 
to the second (current) section. 
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a | 


Type: 
Plink86p/us Statement Key Word 


Purpose: 


Outputs object module names to the symbol table. 


Syntax: 
MTABLE 


Background: 
By default, Plink86p/us outputs the object's file name to the 
symbol table. MTABLE outputs the module name instead. 
Input: 
MTABLE has no arguments. 


Example: 
output test. exe 
file f1, f2 
symtable 
MTABLE 


Generates a symbol table using object module names instead of 
object file names and appends it to the output file TEST.EXE. 
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[== чонан ини АНЫ cc MMNMY 
Туре: 

Plink86p/us Statement Key Word 


Purpose: 
Forces the overlay structure to never use the symbol vector 
address for references to a specified symbol in different sec- 
tions. The real address is used instead. 


Syntax: 
NEVER <symbol>[, <symbol>, ...] 


Background: 


NEVER causes Plink86p/us to override its default method for 
building automatic overlays. Normally, when an address in Sec- 
tion A is a reference to a symbol in Section B, Plink86p/us 
automatically substitutes the symbol vector address for the real 
address, except when Section A is a descendant of Section B. 


NEVER instructs Plink86p/us to always use the real address 
(‘never' substitute the symbol vector address) for the specified 


symbol or symbols. 


Input: 
NEVER is followed by the <symbol> name or names to always use 
the real address for. <symbol> arguments are separated by a 
comma and a space. 


Example: 
NEVER SIN, COS, TAN 


Instructs Plink86p/us to always use the real address for external 
references to symbols named SIN, COS and TAN. 
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Туре: 
Plink86p/us Statement Key Word 


Purpose: 
Suppresses beeps that sound when Plink86p/us error messages 
are displayed. 


Syntax: 
NOBELL 


Background: 
Normally, a beep is sounded and a message is displayed when an 
error is detected or at the end of Plink86p/us processing. 
NOBELL suppresses the beep and displays just the message. 


Input: 
NOBELL has no arguments. 


Example: 
plink86 NOBELL @plitest.Ink «cr» 


Causes Plink86p/us to suppress beeps. 
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Plink86p/us Statement Key Word 


Purpose: 
Suppresses automatic library search requests. 


Syntax: 
NODEFLIB 


Background: 


Automatic library search requests are embedded in object files 
by Microsoft and other compilers. NODEFLIB suppresses these 
requests. 


Input: 
NODEFLIB has no arguments. 


Example: 
output test.exe 
NODEFLIB 
file f1, f2 
library fortran.lib 


Links the object files and library file in the output file but 
suppresses automatic library search requests contained in the 
object files. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Eliminates all local symbols and line numbers from the symbol 
table. 


Syntax: 
NOLOCALS 


Background: 


NOLOCALS can keep the number of symbols in the symbol table 
to a manageable level. Typically, there are many more local 
symbols than global (public) symbols. For large programs, the 
symbol table can become too large for the Pfix86p/us debugger 
to handle if local symbols are included. Only public symbols are 
loaded in the symbol table when NOLOCALS is used. 


input: 
NOLOCALS has no arguments. 


Note: 


Alternatively, the LOCALS statement can include local symbols 
from select modules only and the GLOBALS statement can 
include selected global symbols only or globals in selected files or 
modules only. 


Example: 


output test.exe 
symtable 

file f1 
NOLOCALS 


Excludes local symbols and line numbers from the symbol table 
generated from F1 that is appended to TEST.EXE. 
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Type: 
PlinkB6p/us Statement Key Word 


Purpose: 


Specifies selected public (global) symbols that are not globally 
accessible after an object file merge. 


Syntax: 
NOPUBLICS <symbolname>[, <symbolname> ...] 


Background: 


By default, all public symbols remain globally accessible when 
object files are merged. NOPUBLICS causes specified symbols to 
become private; all other global symbols remain public. 


Input: 
NOPUBLICS is followed by the <symbolname> of the global 
symbol or symbols that will not remain public in the new object 
file. <symbolname> arguments are separated by a comma anda 
space. 


Example: 


output test. obj 
file a.obj, b.obj, c.obj 
NOPUBLICS 51, S2, S3 


Forces the public symbols S1, S2 and S3 to remain static when 
the specified object files are linked in the merged TEST.OBJ. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Changes the way addresses are computed for certain references 
to external symbols in object files. NOSYMGROUP is only used 
when object files generated by Microsoft pre-version 3.2 Pascal 
and FORTRAN compilers are linked. 


Syntax: 
NOSYMGROUP 


Background: 


NOSYMGROUP disables an obscure feature of the Inte! 8086 
object format. This statement must be used for version 1 of the 
Microsoft Pascal and Fortran compilers. It must not be used with 
versions 3.2 or newer of these compilers. It should be used with 
versions between version 1 and version 3.2 of these compilers. 


If addresses are not generating correctly in the linked program, 
save the .EXE file and run Plink86p/us again with NOSYMGROUP. 
Then use COMPARE to compare the two .EXE files. 


Input: 
NOSYMGROUP has no arguments. 


Example: 
plink86 NOSYMGROUP @test.Ink «cr» 


Loads the link program TEST.LNK with NOSYMGROUP activated. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 
Disables TYPDEF record processing in Plink86p/us. 


Syntax: 
NOTYPCHECK 


Background: 


NOTYPCHECK is required for linking large programs compiled 
with the Intel PL/M or Microtech Research Professional Pascal 
compilers. These compilers create TYPDEF records as large as 
1024 bytes, but Plink86p/us only recognizes record size up to 512 
bytes. 


Do not use NOTYPCHECK with Microsoft Fortran 3.3 or newer, 
with Microsoft C 3.0 or newer, or with Microsoft Pascal 3.3 or 
newer. Undefined symbols will occur. 


Input: 
NOTYPCHECK has no arguments. 


Example: 


————————–ыыы 


plink86 NOTYPCHECK @test.Ink 


Loads Plink86p/us with input inserted from TEST.LNK and TYPDEF 
record processing disabled. 
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NOVECTOR 
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Type: 
Plink86pius Statement Key Word 


Purpose: 


Effectively sets the NEVER statement for all variables in specified 
files only, prohibiting Plink86p/us from vectoring any of those 
symbols. 


Syntax: 
NOVECTOR <filename>[, «filename», ...] 


Background: 


Normally, Plink86p/us substitutes the symbol vector address for 
the real address as its default method for building automatic 
overlays. The NEVER statement causes PlinkB6p/us to not substi- 
tute the symbol! vector address for all symbols in all files. 
NOVECTOR sets NEVER for symbols in selected files only. 


NOVECTOR can improve program execution time, especially 
when used in conjunction with the RELOAD statement. All calls 
outside the section will be vectored during RELOAD , but NOVEC- 
TOR will inhibit vectoring for those symbols in the root that do not 
load overlays. 


Input: 
NOVECTOR is followed by the «filename» of the file or files to 
inhibit symbol vectoring in. 

Example: 


file a.obj, b.obj 
NOVECTOR b.ob} 


Links A.OBJ and B.OBJ with symbol vectoring disabled for sym- 
bols in B.OBJ only. 
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Type: 
Рііпк86р/иѕ Statement Key Word 


Purpose: 
Changes the width of symbol names and other identifiers that 
appear on memory map reports to the specified number of 
characters. 


Syntax: 
NWIDTH «number of characters» 


Background: 
NWIDTH is useful when programming languages with long identifi- 
ers are used, such as Pascal and C. 


Normally, Plink86p/us symbol names and other identifiers default 
to nine characters maximum for map reports when NWIDTH is 
not used. When a name exceeds the specified width, it is 
truncated to fit in the report column. 


NWIDTH affects only the map reports. It has no influence on 
comparing identifier names as the program is being linked. More 
or fewer columns will fit on the page when NWIDTH is used. 
Names that exceed the specified width are still truncated to fit in 


the report column. 


Input: 
NWIDTH is followed by the «number of characters» to set for 
symbol name width on the MAP report. 


Example: 
NWIDTH 18 


Changes the symbol name width for map reports to 18. 
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Type: 
PlinkB6p/us Statement Key Word 


Purpose: 


Creates a .EXE file to hold the linked program or creates a .OBJ 
file to hold merged object files. 


Syntax: 
OUTPUT «filename» [.EXE] | [.OBJ] 


Background: 


If OUTPUT is not used, PlinkB6p/us automatically generates an 
output file using the primary name from the first input file and the 
file type .EXE. OUTPUT specifies a different file name to use for 
the output file. For merged object files, OUTPUT merges files 
specified by the FILE statement into a single new .ОВЈ file. 


Input: 


OUTPUT is followed by the «filename» of the output file. File type 
.EXE is the default if not specified. This file overwrites any existing 
file with the same name. 


Options: 
File type .EXE creates an output file linking all modules listed in 
input object files specified with the FILE statement. 


File type .OBJ creates a merged object file that combines all 
input object files specified by the FILE statement. 
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Examples: 
OUTPUT test.exe file a.obj, b.obj 


Creates an output file TEST.EXE that links object files A and B 


OUTPUT test.obj file a.obj, b.obj 
Merges file A and file B in an object file named TEST.OBJ. 
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OVERLAY 
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Type: 
Plink8B6p/lus Statement Key Word 


Purpose: 


Specifies segment classes that can remain in the overlay struc- 
ture. This statement is not required for normal operation. 


Syntax: 


OVERLAY <classname>[, <classname>, ...] 


Background: 
Plink86p/us normally places the first class defined by the program 
modules into the overlay structure and moves all other classes to 
the very end of the program. This is usually correct because the 
first class contains code segments and is the class to be overlaid 
for most compilers. 


OVERLAY overrides the normal class placement method by 
placing the specified classes in overlaid sections of the program. 
All other classes are moved to the end of the program as before. 


Input: 


OVERLAY is followed by the <classname> of the class or classes 
to remain in the overlay structure. <classname> arguments are 
separated by a comma and a space. 


Example: 
OVERLAY CODE, DATA 


Specifies that segments in the classes named CODE and DATA 
will remain in the overlay structure. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Instructs the overlay loader to load a specified overlay section 
into memory before passing control to the user program. 


Syntax : 
PRELOAD 


Background: 
Normally, only resident sections of the program are loaded into 
memory before control is passed to the user program. PRELOAD 
loads the specified overlay section at the same time as the 
resident sections. 


Input: 
Insert PRELOAD in the statement input immediately following the 
SECTION statement for the overlay section you want to preload. 
PRELOAD has no arguments and applies only to the section that 
precedes it. 


Example: 


output test.exe 
section = root 
file f1.obj, f2.obj 


beginarea 
section = ov1 file a 
section = ov2 PRELOAD file b 
section = ov3 file c 
endarea 


Loads the root section and the overlay section named OV2 into 
memory before control is passed to the program. Only the root 
section would be loaded in advance if PRELOAD was not used. 
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PUBLIC 


Type: 
Plink86p/us Statement Key Word 
Purpose: 


Allows only specified symbols to remain public and merged into a 
new object file by OUTPUT <filename.OBJ>. 


Syntax: 


PUBLIC [<symbolname>[, <symbolname>, ...]] 


Background: 


By default, all public symbols remain public when object files are 
merged. PUBLIC forces all or some of these symbols to become 
private and suppresses them from the merged object file. 


PUBLIC makes the object file slightly smaller because there is 
less compiler data in the object file. PUBLIC also reduces the 
chance that users of your merged object file will step on your 
symbols (i.e., have their own symbols with the same names). 


ире с. 


Input: 


PUBLIC with no arguments suppresses all public symbols from 
the merged object file. 


Options: 


PUBLIC followed by the <symbolname> of a symbol or symbols 
causes those symbols to remain public in the new object file. All 
other globals are suppressed in the merged object file. <symbol- 
name> arguments are separated by commas. 
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Example: 
output test.obj file a.obj, b.obj, c.obj 


PUBLIC S1, S2, S3 


Forces all symbols except S1, S2 and 53 to become private when 
the specified object files are linked in the merged TEST.OBJ. 
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RELOAD 
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Туре: 
Plink86p/us Statement Key Word 


Purpose: 


Automatically reloads overwritten overlays as required upon di- 
rect or indirect function return. 


Syntax: 
RELOAD NEAR|FAR <stackdepth> 


Background: 


RELOAD causes the overlay loader to reload an overlay that was 
overwritten by a previous call. For example, if A.OVL calls a 
function in B.OVL, and B.OVL overlays A.OVL, the system will 
hang when the program attempts to return to its caller, A.OVL. 
With RELOAD, the overlay loader reloads A.OVL automatically by 
replacing the real function return address in the stack with the 
address of a routine that performs the reloading procedure. 


RELOAD will work with most 8086 high level language compilers. It 
will not work with compilers whose assembly language function 
arguments are not pushed on the stack. These arguments appear 
“in line” after the function call instruction. They are accessed via 
the return address in the stack, but RELOAD substitutes a return 
address that points inside the overlay loader and not to the 
function arguments. 
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Input: 
RELOAD is followed by either NEAR or FAR and the <stackdepth>: 


y NEAR|FAR specifies whether the code is "near" or "far" in the 
program and must match the NEAR|FAR setting for the compiler 
or unpredictable results can occur. 


«stackdepth» specifies the amount of memory to reserve for the 
| stack. It is entered as the maximum number of nested calls (in 
hex) that will be made to overlaid functions during execution. 


, . 
ЖР”... жуу». атъ 


| 


Notes: 
The reload stack always uses six bytes per call, so the stack size 
is the specified number of calls multiplied by six bytes. If the 
requested stack space is not available at run time, or if the stack 
overflows (too many nested function calls), the program is 
terminated by the overlay loader. 


Note for C users: 
The run-time libraries of some compilers manipulate the return 
address on the stack for their own purposes. If a non-RELOADing 
version crashes, that may be a problem. Try creating the version 
with RELOAD, but NOVECTOR the run-time library: 


LIB COMPILER.LIB 
NOVECTOR COMPILER.LIB 


Note for C applications: 

Using setjmp/longjmp when RELOAD or TRACK is invoked can 
create problems for the internal stack. Also, if a longjmp is 
performed into a non-resident overlay, the program will crash. 
However, the OVERLAY.LIB routines $OVSAVE and $OVRES- 
TORE may be used to manage the reloading stack and overlay 
context. Refer to Appendix C, "Overlay Loader" for information 
about modifying the assembler file OVSTACK.ASM. 
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Warning: 


Do not use RELOAD at the same time as ALLOCATE in a large 
code model. Some run-time libraries mix far and near calls and 
the program may not run if these library routines are placed more 
than 64kB from the overlay table. 


Microsoft C Note: 
Reloading with a small model Microsoft C application requires use 
of the large model syntax (RELOAD far stack_depth). Since the 
run-time libraries mix far and near calls, the far syntax must be 
used to cover both cases. If a near call cannot be vectored, the 
module that refers to it must be moved to within 64kB of the start 
of the overlay table. 


Examples: 
RELOAD near 100 


Activates automatic reload for NEAR program code with a 100 
(hex) call stack. ^ 


RELOAD far 200 1 


Activates automatic reload for FAR program code with a 200 
(hex) call stack. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 
Defines libraries for input to the linkage edit the same as the 
LIBRARY statement, but causes Plink86p/us to make multiple 
passes through the specified library files if undefined symbols 
remain after the files have been read. 


Syntax: 
SEARCH «libraryname»[, <libraryname>, ...] 


Background: 


SEARCH is useful for situations where all required modules 
cannot be extracted from the library in one pass, such as when 
two libraries are being searched that each refer to symbols 
defined in the other. 


Not all modules are selected for input from the specified library. 
SEARCH selects only the library modules that define symbols that 
were previously declared external and are currently undefined in 
the already-linked modules. 


Input: 


SEARCH is followed by the «libraryname» of the library file or files 
to include in the search. «libraryname» arguments are separated 
by a comma and a space. .LIB is the default file type unless 
otherwise specified. 


Example: 
SEARCH a.lib, b.lib 


Identifies A.LIB and B.LIB as input library files that should be 


| | 
M searched again if undefined symbols remain after the files have 
been read. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Creates a program section that is loaded from disk as a separate 
unit. 


Syntax: 
SECTION [= <sectionname>] [INTO <filename>] 


Background: 
Overlayable segments obtained with FILE, LIBRARY or SEARCH 


statements that follow the SECTION statement are loaded into 
that section by default. 


If SECTION is omitted, Plink86p/us creates a section automati- 
cally when a statement such as FILE, LIBRARY or SEARCH is 
encountered that requires a section to put things in. 


The SECTION statement is typically used to force a new section 
in the program or to redundantly show for documentation pur- 
poses where in the input Plink86p/us creates a new section. 


Input: 


SECTION with no arguments creates a new section to hold 
overlayable segments identified in subsequent FILE, LIBRARY or 
SEARCH statements. 
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SECTION, Continued 


Options: 
[= sectionname] specifies a section name that will appear on 


memory map reports. 


{INTO <filename>] places the overlay section into the specified 
.OVL disk file instead of the executable file. 


Example: 
SECTION = section! file a, b 
SECTION INTO test1.ovl file c, d 


The overlayable segments from the modules in files A and B are 
assigned to a section named SECTION1. SECTION INTO places 
overlayable segments from the modules in files C and D into the 


separate overlay file TEST1.OVL. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Changes the size of the stack defined in the .EXE file header to 
the number of bytes specified. 


Syntax: 
STACK <number of bytes> 


Background: 


STACK is typically used to support Fortran compilers, including 
the Microsoft version 3.x Fortran compiler, the IBM Professional 
FORTRAN compiler and the Ryan McFarland FORTRAN compiler. 


With non-FORTRAN compilers, the stack is routinely discarded 
during execution and a new one built in available memory, so the 
STACK command is not normally required. 


Input: 


STACK is followed by the hexadecimal <number of bytes> to use 
for the stack defined in the .EXE file header. 


Note: 


All stack segments are forced to a paragraph-aligned memory 
address for compatibility with the Microsoft Basic compiler. 


Example: 
STACK 800 


Creates an 800 (hex) byte stack (2kB). 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Selects the way the Intel 8086 object format is handled by 
Plink86p/us, specifically the way addresses are computed for 
certain references to external symbols in object files. 


Syntax: 
SYMGROUP 


Background: 


SYMGROUP is set as the default for Plink86p/us. This is the 
opposite of older versions of the program. SYMGROUP is in- 
cluded here for compatibility with input files prepared for those 
versions. 


Refer to the NOSYMGROUP statement in this chapter for informa- 
tion about when to use NOSYMGROUP to override this default 
setting. 


Input: 
SYMGROUP has no arguments. 


Example: 


output test.exe 
file test.obj 
SYMGROUP 


Links TEST.OBJ with SYMGROUP activated. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 


Generates a symbol! table for use with the Pfix86p/us symbolic 
debugger or the Pfinish performance analyzer. 


Syntax: 
SYMTABLE 


Background: 


SYMTABLE appends a symbol table to the end of the .EXE file 
created by the linkage edit. This table contains information about 
the names and addresses of symbols in the program. 


This information is used by the Pfix86p/us debugger and Pfinish 
program analyzer. All symbols encountered in the program are 
placed in the symbol table. 


A note about local symbols: Some compilers generate object file 
records that give addresses for local symbols or source line 
numbers within the module being compiled. These local symbols 
and source line numbers are added to the symbol table by 
Plink86p/us except when the LOCALS or NOLOCALS statement is 
used. These statements limit or disallow local symbols in the 
symbol table. 


Input: 
SYMTABLE has no arguments. 


Note: 


Use the SYMTABLE.EXE utility program to list or delete symbol 
tables generated by the SYMTABLE statement. 
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Example: 


output test.exe 
file f1, f2 

lib fortran.lib 
SYMTABLE 
nolocals 


Generates a symbol table that contains all public symbols (but not 
local symbols) encountered while object files F1 and F2 and 
library FORTRAN.LIB are being linked in TEST.EXE. This symbol 
table is appended to the output file TEST.EXE. 
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Plink86p/us Statement Key Word 


Purpose: 


Strips all debugging information from object files that are merged 
into a single file by the OUTPUT «filename.OBJ» statement. 


Syntax: 
TINY 


Background: 


Normally, when object files are merged, Plink86p/us includes all 
information from the compiler in the resulting composite output 
file. TINY causes all debugging information and comment records 
to be stripped from the new composite output file. This produces 
a slightly smaller object file since there is less compiler informa- 
tion included. 


Input: 
TINY has no arguments. 


Example: 


output test.obj 
file a, b, c 
TINY 


Combines A.OBJ, B.OBJ and C.OBJ into TEST.OBJ, but strips all 
debugging information and comment records from TEST.OBJ. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 
Effectively enables RELOAD for selected symbols only. 


Syntax: 
TRACK «stackdepth» «symbolname»[, «symbolname», ...] 


Background: 


RELOAD causes the overlay loader to automatically reload over- 
lays that were overwritten by previous calls. TRACK enables 
reloading for selected symbols only. Unlike RELOAD, TRACK 
does not require a NEAR or FAR specification. Instead, TRACK 
behaves as though RELOAD FAR is enabled for the specified 
symbols. Using TRACK instead of RELOAD can improve perform- 
ance for some applications. 


Input: 
TRACK is followed by the desired «stackdepth» and the «symbol- 
name» of the symbol or symbols to invoke automatic reloading 
for. Symbols are separated by a comma and a space in the input. 


«stackdepth» specifies the amount of memory to reserve for the 
stack. It is entered as the maximum number of nested calls (in 
hex) made to overlaid functions during program execution. 


Note: 
The reload stack always uses six bytes per call, so the stack size 
is the specified number of calls multiplied by six bytes. If the 
requested stack space is not available at run time, or if the stack 
overflows (too many nested function calls), the program is 
terminated by the overlay loader. 
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Example: 
TRACK 100 S1, S2, S3 


Activates automatic reload for S1, S2 and S3 only, with a 100 | 


(hex) call stack depth. 
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Type: 
PlinkB6p/us Statement Key Word 


Purpose: 


Forces Plink86p/us to translate all identifiers and symbols to upper 
case. 


Syntax: 
UPPERCASE 


Background: 


By default Plink86p/us uses the original upper or lower case freely 
mixed for all identifiers and symbol names. UPPERCASE over- 
rides this default and forces all identifiers and symbol names to 
upper case. 


Input: 
UPPERCASE has no arguments. 


Examples: 
plink86 UPPERCASE @test.Ink «cr» 


Loads PlinkB6p/us with input inserted from TEST.LNK and trans- 
lates all identifiers and symbols to upper case in the linked 
program. 
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PlinkB6p/us Statement Key Word 


Purpose: 
Displays a status line at the console that identifies the task 
Plink86p/us is currently executing. 

Syntax: 
VERBOSE 


Background: 


The status line is useful for following the linkage edit in progress 
and for debugging to find the operation that may be causing a 
problem in the linkage edit. 


The VERBOSE statement slows down the linkage edit consider- 

ably. You may want to use it only as you are learning how to use 

Plink86p/us or if you are having problems linking your file. 
Input: 

VERBOSE has no arguments. 


Note: 


This statement should not be used on a teletype-like terminal as 
it will continuously rewrite the same line. 


Example: 
plink86 VERBOSE @test.Ink 


Loads Plink86p/us with input from TEST.LNK and displays the 
status line as the program executes. 
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Туре: 
Plink86p/us Statement Key Word 


Purpose: 
Sets the page width of the memory map reports to the specified 


number of characters per line. 


Syntax: 
WIDTH <number of characters> 


Background: 
Plink86p/us memory map reports default to 80 characters per line 


when WIDTH is not used. 


Input: 
WIDTH is followed by the <number of characters> per line to set 


for MAP reports. 


Example: 
WIDTH 132 


Sets page width to 132 characters per line for MAP reports. 
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Type: 
Plink86p/us Statement Key Word 


Purpose: 
Specifies a file name other than the default PLINK86.WRK and 
optionally specifies a drive and path for the Plink86p/us temporary 
work file. 

Syntax: 
WORKFILE=[d: path\]<filename> 


Background: 
Plink86p/us automatically pages program descriptions to a tem- 
porary work file on disk if there is not enough memory available 
during processing. This file, named PLINK86.WRK by default, is 
created in the current directory. WORKFILE names the work file 
as specified and optionally redirects it to a specified drive and 
directory path. 

Input: 
WORKFILE=<filename> provides a different name for the 
Plink86p/us temporary work file. 

Options: 


[d:path\] provides a drive and path reference for the work file. 


Example: 
WORKFILE=b:sub1\temp.wrk 


Creates the Plink86p/us temporary work file in a Drive B subdirec- 
tory named SUB1 and names it TEMP.WRK. 


Page 9-80 PlinkB6 plus User Manual 


і 


| 


N 


E N 


Utility Programs 
Беда сапалы Eee 
Plink86p/us includes several utility programs to assist you with the 


process of managing the linkage edit. These utility programs are 
contained in .EXE files on the Plink86p/us distribution disk. 


Plink86p/us utility programs are as follows: 


PROGRAM FUNCTION 


CHECKSUM.EXE Validates the checksum of any 
.EXE file. 

COMPARE.EXE Performs a byte-by-byte comparison 
of two files. 

DUMP.EXE Copies the contents of a file in a 
variety of readable formats. 

SYMTABLE.EXE Prints or deletes a symbol table. 


The Plib86 utility program (PLIB86.EXE) is also included on the 
Plink86p/us distribution disk. This program can create and man- 
age object library files for use with PlinkB6p/us. Plib86 is de- 
scribed in Chapter 11, "Plib86 Library Manager." 
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CHECKSUM.EXE 
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Type: 
Plink86plus Utility Program 


Purpose: 
Validates the checksum of any .EXE file. 


Syntax: 
CHECKSUM <filename> <cr> 


Background: 


The file CHECKSUM.EXE is required to execute this program. 
CHECKSUM checks for a valid .EXE signature, then adds all 
words in the file. If they produce OFFFFH, the message “Check- 
sum OK” is displayed. Otherwise, the checksum obtained is 
displayed with the message “Invalid Checksum.” This means the 
.EXE file may be corrupted. 


Input: 
CHECKSUM is followed by the <filename> of the file to check. 


Examples: 
CHECKSUM plink86.exe <cr> 


Validates the checksum of the file PLINK86.EXE. 
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COMPARE.EXE 
Былшық НЕН 


Туре: 
Рііпк86р/иѕ Utility Program 


Purpose: 
Performs a byte-by-byte comparison of two files and displays the 


results at the console. 


Syntax: 
COMPARE <file1> <file2> [START «address» SIZE <bytes>] 
[DISK] «cr» 


Background: 
The file COMPARE.EXE is required to execute this program. When 
differences are found in the compared files, the mismatched 


bytes from both files are listed. 


Input: 
COMPARE is followed by the <file1> and <file2> to compare. 
These arguments are separated by a space. 

Options: 

[START «address» SIZE «bytes»] compares the portion of the 

files specified by the offset and size. 

[DISK] copies the report to a disk file named COMPARE.DIF. | 


Examples: 
COMPARE file1 file2 <cr> 


Compares FILE1 and FILE2 and displays the results on the 


console. 
COMPARE f1 12 start 21c5 size 20 disk «cr» 


Starts at offset 21C5 for 20 bytes only and copies the report to 
the disk file COMPARE.DIF. 
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Type: 
Plink86p/us Utility Program 


Purpose: 
Copies the contents of a file in a variety of readable formats on 
the console or in a disk file. 


Syntax: 

DUMP «filename» [disk] [fixup] 
[module «name»|symbol «name»] 
[include «name[, name]>|exclude 
«name[, name]» 
[hex [start «address» 
[size «bytes»] 
[exe|obj|lib|asc] «cr» 


Background: 


The file DUMP.EXE is required to execute this program. The 
dump is displayed at the console by default. 


Input: 


DUMP is followed by the «filename» of the file to dump. .EXE is 
assumed if file type is not specified. Report format depends on 
the file type: 


EXE: Header and all base fixups. 


OBJ: Microsoft or Intel object record format. 


LIB: Each module in Microsoft or Intel object record | 
format. 


For other file types, the dump is in hex with ASCII interpretation і 
included for each line. ж 
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Options: 
[ASC] forces ASCII format dump. 


[DISK] copies the report to a disk file and names it with the 
primary name from the file being dumped and the file type .LST. 
The report is displayed on the console if [DISK] is omitted. 


[EXCLUDE <name[, name]>] excludes the specified object file 
record types. 


[EXE] forces .exe-type dump. 
[FIXUP] enables printing of base fixups from the .EXE report. 
[HEX] forces a hex dump. 


[INCLUDE «name[, name]»] includes records of the specified 
record types only. <name[, name]» is a list of the Intel record 
names or hex record type numbers to include. Refer to the Intel 
object format documentation for record type names. INCLUDE is 
valid only on .OBJ and .LIB files. 


[LIB] forces .lib-type dump. 
{MODULE <name>] selects a single module for the .LIB report. 
[OBJ] forces .obj-type dump. 


[START «address» [SIZE «bytes»]] forces use of the start ad- 
dress and size as specified. 


[SYMBOL <name>] selects a single module where the specified 
public symbol is defined for the .LIB report (if present in the 
library index). 
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Examples: 
DUMP test.exe 


Dumps TEST.EXE to the console. 


DUMP test.lib module xios «cr» 
Dumps the module XIOS in the library TEST.LIB. 
DUMP test.lib symbol printf «cr» 
Dumps the module containing PRINTF in the library TEST.LIB. 
DUMP test.obj include theadr «cr» 
Includes the THEADR record in the dump of TEST.OBJ. 
DUMP test.obj exclude 0a0, 9c «cr» 
Excludes record types ОАО and SC from the dump of TEST.OBJ. 
DUMP test.lib hex disk «cr» 


Dumps all modules in TEST.LIB in hex format to the file TEST.LST. 


DUMP test.Ink start 100 size 80 «cr» 


Dumps TEST.LNK in hex starting at offset 100 for 80 bytes. 
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SYMTABLE.EXE 
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Туре: 
Plink86p/us Utility Program 


Purpose: 


Prints or deletes a symbol table. 


Syntax: 
SYMTABLE <filename> [DELETE] <cr> 


Background: 


The disk file SYMTABLE.EXE is required to execute this program. 
The symbol! table is printed at the console by default. 


Input: 


SYMTABLE is followed by the <filename> of the .EXE file to 
search for a symbol table. An error message is displayed if the 
file cannot be found, is not a .EXE file or does not contain a 
symbol table. 


Options: 


[DELETE] (or DEL) deletes the symbol table. This is useful if your 
program has been debugged and you don't want to relink it just to 
remove the symbol table. The .EXE file is renamed as file type 
'.$$$' and then copied back to the original .EXE file with the 
symbol table omitted. The program terminates if there is not 
enough disk space. 


Examples: 
SYMTABLE test.exe «cr» 


Prints the TEST.EXE symbol table. 
SYMTABLE test.exe delete «cr» 


Deletes the TEST.EXE symbol table. 
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CHAPTER 10 - 
WARNING AND ERROR MESSAGES 


Overview 


This chapter describes error and warning message numbers that 
Plink86p/us can display during operation. 
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Plink86p/us Messages 
Pe ee ee ЕЕЕ ЕЕЕ ees ae ees | 


Error and warning messages are displayed at the console by 
Plink86p/us when a problem or potential problem is encountered. 
These messages, while terse, are usually enough to explain the 
problem. 


The message number that appears with the error or warning 
message is a reference to a number in this chapter. A detailed 
description of the problem is provided here for each number 
along with possible solutions. 


This chapter is divided into two sections: 


Warning Messages 


Warning messages are issued if Plink86p/us detects a condition 
that may present a problem during the linkage edit. Warning 
messages are advisory only. The warning message is displayed 
and Plink86p/us continues. 


Error Messages 


Error messages are issued when an error condition is detected. 
Depending on the error, Plink86p/us allows input to correct the 
problem or exits to DOS. 
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Warning Messages 


| NUMBER | DESCRIPTION 


Offset <offset> is out of range with 
reference to «symbol». 


Indicates a location being referenced by a 
16-bit address is more than 64kB away, 
or the address being referenced is lower 
in memory than the location of the seg- 
ment register that is assumed. 


Example: If a near call is made to a 
memory address that is lower than the 
current CS, the program may not address 
the object correctly. This can also occur 
if a far call is made that uses the wrong 
segment address. The calculated offset 
will overflow its 16-bit word. If the object 
is in a group larger than 64kB, a “group 
too large” warning is also issued. 


Note: This warning may also be generated 


if the SYMGROUP or NOSYMGROUP 
statements are not properly set when 
linking object files generated by 
pre-version 3.2 Microsoft Pascal 

and Fortran compilers. 


No stack segment defined, zero used. 


Indicates the segment that normally 

identifies the desired stack location cannot 
be found by Plink86p/us. The stack statement 
sets the SS and SP registers when the 
program is loaded. It is marked as the 

stack segment by the assembler or compiler. 
Its eventual address is placed into the 

header of the .EXE file. 


If the stack segment cannot be found. 
Plink86p/us loads zeros in the .EXE file header 
instead. in this case, the program will 
function correctly only if it sets the registers 
itself, and even then it could crash if an 
interrupt occurs before a valid stack is 

set up. 


CONTINUED 
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| NUMBER | DESCRIPTION 


«group» size of «size» is larger than 64kB. 


Indicates the segments that make up the 
group do not reside within a 64КВ memory 
space. 16-bit addresses are used to 
access objects within the group, so all 
segments cannot be accessed if the group 
is larger than 64kB. The solution is to 
reduce the size of the group or use 
overlays to decrease its memory require- 
ment. This message might be issued even 
when it appears the segments comprising 
the group are less than 64kB. Check the 
memory map for segments that have been 
separated by intervening segments not in 
the group. 


Assembly Language Note: 
When assembly language modules are 
mixed with modules from a high-level 


language, the class and segment names 
used in the assembler language and high- 
level language should match. If they do not 
match, the assigned memory addresses for 
the assembler segments will probably be 
placed at the end of the section and too 

far away from the group. 


Microsoft Assembler Note: 

With pre-3.0 versions, a dummy segment 
with no class name is created if a segment 
used in a GROUP statement is never de- 
fined. The dummy segment will not combine 
with other data segments. Check your MAP 
report for segments with no class names. 
MASM 3.0 creates a reference to a segment 
index of 0 instead, which is also incorrect. і 


MASM 4.0 апа Pasm86 handie this situation 
correctly by reporting the error and not 
creating the object file. 


Microsoft Fortran Note: 
Use common blocks to handle DGROUP Р 
overflows. 


CONTINUED 
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Warning Messages, Continued 


Can't find <module>. 


Indicates the module identified in the 
MODULE statement cannot be found. Use 
the DUMP utility to review module name 
records (DUMP <filename> INC THEADR). 
The module name might not be the same 
as the file name, and some compilers use 
the same name for all modules compiled. 
By default, Plib86 uses the module name 
when a module is inserted into a library. 
You can force use of the file name with the 
MODRENAME statement. 


No starting address given, zero used. 


The starting address is kept in the .EXE file 
header. If Plink86p/us cannot find a module 


marked with a starting address, zeros are 
used and the program begins execution at 
the first location. 


Unknown record type «type» in «module». 


Indicates Plink86p/us cannot recognize a record- 
type in the named module, so it skips the 
entire record. These messages are 

inhibited after a few have been issued. 


Checksum error in «module». 


Indicates the checksum in the check field 
at the end of an object file was invalid, but 
linking continues. These messages are 
inhibited after a few have been issued. 
Object files patched on disk before the link 
can cause this message if the checksum 
was not changed. Library managers or 
compilers that do not generate checksums 
correctly can also cause this message. A 
fatal error will occur shortly after this 
message if the file is truly smashed. 


CONTINUED 
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Warning Messages, Continued 


| NUMBER DESCRIPTION 


Record size error «size» in «module». 


Indicates Plink86p/us reched the end of an 
object file record and the number of bytes 
processed is different than the number of 
bytes specified in the word preceding the 
record. The specified size may be found 
with the DUMP utility. The object file con- 
taining the mismatched record is probably 
smashed, but Plink86p/us continues 
processing until a fatal error occurs. 


Can't reach <base1>+<offset> from 
«base2». 


indicates the target object is more than 
64kB away when referenced from within the 
named module. This occurs when the seg- 
ment register points to the given object 
frame, but the object is more than 64kB 
away and cannot be accessed by the 16-bit 
address. The address actually used is 
wrapped around to fit into the required 
offset size. Use a memory map to 
determine if any group is larger than 64kB. 
Make the offending group smaller correct 
access. 


This warning may also be generated if the 
SYMGROUP or NOSYMGROUP statement 
are not properly set when linking object 
files generated by pre-version 3.2 
Microsoft Pascal and Fortran compilers. 


Duplicate «symbol» in «module». 


Indicates more than one definition was found 
for a public symbol in the program being 
linked. This message is issued when a second 
symbol name is found in another module or 
was manually defined by the DEFINE 
statement. Only one symbol definition for 
each public symbol can be recognized. 
Plink86p/us retains the first definition, ignores 
the duplicate and continues linking. 


CONTINUED 
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Warning Messages, Continued 


| NUMBER | DESCRIPTION 


Duplicate <segment> defined for <module>. 


Indicates the named segment was assigned 
to more than one group. This occurs when 
a module places a segment in a group and 
another module specifies a different group 
for the same segment. References to the 
segment might be incorrectly calculated. 


Duplicate type definition. 


Indicates the named segment was first 
defined as a public segment and later 
defined as a common block, or vice versa. 
This occurs when assembly language 
modules are being linked and all definitions 
of the segment are not the same type. 


Duplicate stack <segment> in <module>. 
Indicates a duplicate stack segment was 
defined within the named module. Plink8Go/us 
uses the last stack definition to specify the 
stack in the .EXE file header for compat- 
ibility with Microsoft LINK . If this stack 
segment is empty or too small, the user 


program will probably crash. Since the previous 
stack segment is ignored, there is no point in 
having more than one stack segment. All stack 
segment definitions should use the same 
segment and class names. They will then be 
combined into one segment that is the sum of 
the sizes of the original segment. 


Type mismatch. 


Indicates you are declaring a symbol differ- 
ently in different files, such as an integer 

in one file and a long in another file. This 
message can also be generated in you are 
mixing assembler/compiler code or using two 
different compilers. The use of type 
definitions is not generally consistent across 
compilers, even if they produce the same 
format. Use the DUMP utility to see if 
TYPDEF records are the same. 


CONTINUED 
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Warning Messages, Continued 


Symbol is near plus far. 


This warning occurs if two different types of 
fixups have been generated for the same 
symbol, such as a symbol that is referenced 
as a near symbol in one case and as a far 
symbol in another case. 


Not enough memory for file path. 


Indicates there is not enough memory to 
save the keyed path string. PlinkB6 plus 
will then prompt again for entry of the path 
string during its second pass through the 


Bad allocation size in section ##. 


If the calculated section size is not the same 
as the actual section size, this warning occurs. 
Plinkplus chooses the largest of the two sizes. 
This should not create any problams with the 
.EXE file generated. 


Bad fixup count in section ££. 


Indicates the Plink86 p/us fixup count 
recorded in the second pass through the 
statement input is not the same as the 
fixup count recorded in the first pass. This 
can occur if you try to move the overlay 
table with the CLASS statement. The 
linked program will probably crash when you 
attempt to execute it. 


Percent value too large: x + y. 


indicates CACHE statement values equal 
more than 100 percent. Plink86 p/us 
automatically adjusts the percentage to 
'100 - minimum required percentage' when 
this occurs. 


is an error in merge 


25 File input more than once 
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Command Syntax Errors 


Syntax errors indicate keying errors in the Plink86p/us input. The 
input line in question is displayed at the console with a pair of 
question marks inserted after the point where the error was 
detected. If the question marks appear at the beginning of a line, 
check the end of the preceding line for the problem. Correct the 
problem and continue. 


— 
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DESCRIPTION 


@ files nested too deep. 

‘@’ files are nested more than three layers 
deep. This error can also be caused by a 
loop in the “@” file references. 


Can’t read @ file. 
A disk error was encountered while reading 
an “а” file. Try rebuilding the file. 


Missing @ file. 
PlinkB6p/us cannot find the specified ‘@' file. 


Input item too large. 
The item given for input at this point 
exceeds 64 characters. 


Invalid digit in number. 
The number contains a digit that is not 
valid for the radix being used. 


Invalid file name. 
The specified file name is not a valid file 
name under DOS. 


Expecting statement. 
A statement was expected at this point 
in the input. 


Can't combine merge and link statements. 
Link commands for merging object files 
cannot be combined with commands for 
linking an executable file. 


Expecting ID. 

An identifier (section, module, segment, or 
symbo! name) was expected at this point 
in the input. 


Expecting =. 
‘=’ was expected at this point in the input. 


CONTINUED 


- 
— 
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Error Messages, Continued 


DESCRIPTION 


Expecting value. 
A 16-bit value was expected at this point 
in the input. 


No files given to link. 

At least one FILE statement must appear 

in Roco input to specify the file or files 
to link. 


Expecting ). 

')' was expected at the end of the CLASS 
statement to enclose the list of segment 
names in parenthesis. 


Input value too large. 

The numerical argument entered exceeds 
the upper boundary condition for the 
statement. 


Expecting percent value. 

The CACHE statement accepts “# of para- 
graphs," “# of kilobytes” or “% of available 
memory" for its arguments. 


Expecting symbol name. 
The PUBLIC statement expects a list of 
symbo! names separated by commas. 


Expecting near or far statement. 
The RELOAD statement expects a description 
of the program code, near or far. 


Invalid cache value: zero percent. 

The effective cache size specified in the 
CACHE statement is zero (i.e., '10096' for 
maximum cache size and ‘100% for minimum 
program requirement). 


Inconsistent statement. А 
Both NOPUBLICS and PUBLICS were seen іп 
the input statements. 
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| NUMBER | DESCRIPTION 


Invalid type record in program. 

Plink86p/us accepts object modules conforming 
to the Intel Relocatable Standard Format. 
Plink86 р/иѕ may not recognize the type of 
object record to process if your module 


contains non-standard records or has been 
corrupted. 


BBS segment too large. 


Microsoft C places uninitialized variables 

into specific segments of class BBS. These 
segments are created by the linker and are 
guaranteed to be initialized to zero at 
run-time. This message is issued if the 
public segment "c common" becomes larger 
than 64kB. 
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Work File Errors 


These errors indicate a problem with processing the temporary 
work file that holds the description of the program if Plink86p/us 
runs out of memory during execution. 


| NUMBER | DESCRIPTION 


Can't create work file. 
There is no space in the disk directory to 
create the work file. 


Can't write work file. 
An МО error occurred while writing the work 
file. The disk may be full. 


Can't read work file. 
An I/O error occurred while reading the 


work file. 


Can't position work file. 
An I/O error occurred while the work file 
was being repositioned with an Iseek. 


Too many objects in program. 

Plink86-Plus has run out of valid handles 

for objects. It may still be possible to link 
the program in stages. Try merging groups 
of object files, and use the PUBLIC 
statement to restrict the number of public 
symbols to those actually needed to link the 
program. 
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input Object File Errors 


These errors indicate a problem with the object files input to 
Plink86p/us. They typically occur when a file has been corrupted 
somehow. Try recompiling to get a new copy of the object file. If 
a library supplied with the compiler is at fault, try to obtain a fresh 
copy of that software. 


| NUMBER | DESCRIPTION 


End of file. 

Premature end of input object file. The end 
of the indicated file was reached un- 
expectedly. Possibly the file was truncated 
by copying it with a program that can only 
handle text files. 


Read error. 
Fatal read error in input object file. 


Can't find file. 

The specified object file cannot be located 
and PlinkB6 plus is being terminated. This 
message appears after Plink86p/us has 
prompted for entry of a file name prefix and 
the operator has elected to terminate the 
linkage edit instead. When BATCH is used, 
this message is issued immediately without 
prompting for input if the object file 

cannot be located. 
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Error Messages, Continued 


Output File Errors 


These errors indicate a problem in creating the output code file 
(or memory map file when written to disk). They are typically 
caused by a full disk or disk directory, a write-protected disk, or 
a hardware problem with the disk. 


| NUMBER | DESCRIPTION 


Can't create file. 

Can't create the output disk file. The disk 
directory may be full, or the disk may be 
write-protected. 


Invalid output file type. 
Ine file type must be .EXE for executable 
iles. 


Write error in file. 


Fatal disk write error in output file. The 
disk may be full or write-protected, or a 
hardware error may have occurred. 

50 


Can't read file. 
Fatal disk read error in output file. An 
irrecoverable hardware error has occurred. 


Can't close file. 
The output file cannot be closed. The disk 
may be write-protected, or a hardware 

error may have occurred. 


Can't create memory map. 
The memory map disk file cannot be 

created. The disk directory is probably 
full, or the disk is write-protected. 
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Error Messages, Continued 


Miscellaneous Errors 


DESCRIPTION 


Undefined symbols exist. 

The listed symbols were external to one or 
more modules but were never defined. 
Define the undefined symbols as publics 
of some module or use the DEFINE 
statement to correct the problem. 


Symbol is self-defined. 

The DEFINE statement defined a symbol 
relative to another symbol and that symbol 
was defined relative to another symbol, etc., 
until the original symbol was reached again 
without a symbol ever being defined. 


Not enough memory. 

There is not enough memory available to 
run Plink86 plus. Plink86p/us requires at least 
256kB of addressable memory to execute. 


Record too large. 

No single record may be larger than 1024 
bytes in the Intel Relocatable Object Format 
Standard. 


Module missing from overlay loader. 
There is a problem with the OVERLAY.LIB 
file. Make sure ee are using the most 
recent version. If you created your own 


OVERLAY.LIB, it must be properly for- 
matted. 


Stack segment is too large. 

The stack segment cannot be larger than 
64kB. Remember that stack segments 
defined in each module are concatenated 
together the same as public segments are. 


CONTINUED 
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Error Messages, Continued 
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DESCRIPTION 


Index number out of range. 
The Intel Relocatable Object Standard does 
not allow forward references within an 


object module. For example, SEGDEF 
records must appear before GRPDEF 
because the GRPDEF record refer to the 
SEGDEF records by number. The DUMP 
utility can help locate a record that refers 
to a segment that is not yet defined. 
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Intel Format Object File Errors 


These errors indicate a problem with the format of the input 
object files. These files should be in the 8086 compiler output 
format defined by Intel Corporation. Sometimes an error occurs 
because the object file is using a feature that Plink86p/us does 
not support. You might be using a compiler that is not supported 
by Plink86p/us. Refer to Appendix G, “Compilers Supported” for 
a list of supported compilers. Another possibility is that the object 
file has been corrupted in some way. Try recompiling the file. 


NUMBER DESCRIPTION 


LTL segment found. 

An LTL segment appeared in an Intel 
module. Plink86p/us does not support LTL 
segments for input. 


Bad register initialization. 

A REGINT record specified a register to be 
initialized in a way that is not supported by 
the .EXE file format. Only the program 
starting address CS:IP and the stack pointer 
ӘЗІР can be pre-initialized with a REGINT 
record. Other kinds of REGINT records 
created by Intel compilers cannot be used 
for .EXE files. 


LIDATA repeat count of zero. 

An LIDATA sub-record has a repeat count 
of zero. This is explicitly disallowed by the 
Intel object format standard. 


Invalid Intel format library. 

An Intel format object library was encoun- i 
tered with a library index that was im- { 
properly formed. It may help to rebuild the { 
library using Plib86. 


CONTINUED 
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Error Messages, Continued 


Starting address is absolute. 

An absolute starting address was specified 
in the given module. Plink86p/us requires a 
starting address relative to some segment. 


Bad group specifications. 
This module uses a group element type not 


handled by Plink86p/us. Only segments may be 
included in groups (group component 
descriptor code = РЕН) used by Plink86p/us. 


Invalid location for self-relative fixup. 
An invalid location was specified for fixup. 
the LOC field is greater than one for a 
self-relative fixup. 


Bad frame number. 
A frame specification type (6 or 7) was 
used that is not supported Бу Plink86 plus. 
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Error Messages, Continued 


Program Structure Errors 


These errors indicate a problem with the specified overlay struc- 
ture. Correct the problem and execute Plink86p/us again. 


| NUMBER | DESCRIPTION 


Overlays nested too deeply. 
Too many levels in the overlay structure 
(32 levels maximum). 


Too many ENDAREA statements. 

The number of ENDAREA statements must 
match the number of BEGINAREA 
statements not yet closed out. 


Not enough ENDAREA statements. 
BEGINAREA and ENDAREA statements are 
unbalanced. There should be the same 
number of each. 


Program size is too large. 

The program being linked will not fit into 
the 1-megabyte maximum address space 
supported by the Intel 8086 processor 
family. Use overlays to reduce the pro- 
gram's memory requirement. 
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Error Messages, Continued 


Diagnostic Errors 


These errors indicate a bug in Plink86p/us has occurred. The 
diagnostic error number is printed to help Phoenix Technologies 
Ltd. locate these problems. If a diagnostic error occurs, try 
running the program again. If the error persists, refer to Appen- 
dix H, "Troubleshooting and Problem Reporting." 


| NUMBER | DESCRIPTION 


No NeedRead buffers in NRNEW. 


Invalid object type in LPOSN. 


Seek error while writing output file in 
OUTSKCHK. 


EN 

EHI 

БЕЛІ Сап" find requested symbol during pass 

2 in EXTDEF. 

Unrecognizable Object in addr32. 

| 209 | Segment has no section. 

[mer] Requested record size too large in NEWREC. 
223 


Requested block number out of range in 
GETBLOCK. 


Null OBJKEY argument. Can't return object 
address in Eaddr. 


CONTINUED 
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Error Messages, Continued 


| NUMBER | DESCRIPTION 


Null objkey argument. Can't return object 
address in Aaddr. 


Null objkey argument. Can't find object 
address in LPOSN. 


No output file defined in Daddr. 


No section lists to assign memory location 
in area. 


Unknown TYPDEF leaf in MERGTYPS. 
Unknown object SEGTYP in PUTSEG. 


Unrecognized alignment type in PUTSEG. 


Unknown leaf type in BSSDEF. 
Unkown BSS type. 


Attempt to reference workfile. 


Zero object key passed to Q/QM. 


Auto-allocation code has reference from 
invalid object. 
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CHAPTER 11 - PLIB86 LIBRARY MANAGER 


Overview 


This chapter describes how to use the Plib86 library management 
utility program to create and manipulate object file libraries. 
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What is Plib86 
Кылы — OPEP SERRE ERU ae ge Ru | 


Plib86 is an object library management system that can build and 
manipulate object library files. Libraries are collections of object 
files containing utility routines and other modules that can be 
input to PlinkB6p/us. 


Run-time libraries are usually included with compiler products 
whose modules are required while the program executes. The 
compiler library contains modules that support the high-level 
features of the language. 


Some application software products are sold in the form of object 
libraries, such as a payables package that may be linked into an 
existing general ledger system. This distribution method is easy 
to maintain and provides many marketing opportunities for pack- 
aging software as a set of functional subsystems. 


Smart programmers create their own libraries to avoid solving 
and re-solving the same basic programming problems. Fre- 
quently-used general purpose routines may be collected in 
libraries and linked into many different programs. 


Plink86p/us uses a library search to link only the library modules it 
requires for the linkage edit. It also uses a library index to find the 
modules quickly instead of searching the library sequentially. 
Plib86 creates a library index for libraries it builds. This index list- 
each public symbol and the module that defines it. 
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What Plib86 Does 
ee 


Plib86 provides library management tools for manipulating object 
module libraries. Plib86 functions include the following: 


e Creating new libraries from individual object files. 
o Merging existing libraries and object files in new libraries. 


e Updating existing libraries with new or replacement object 
modules. 


e Extracting all or selected modules from a library and plac- 
ing them in individual object files. 


e Searching selected libraries and including required mod- 
ules only for input to Plib’6 processing. The library 
search feature allows Plib86 to generate a complete 
cross-reference of the symbols in a program. 


e Providing a library index containing a list of the public 
symbols offered by each library module and the location 
of each module in the library. PlinkB6p/us uses this infor- 
mation to rapidly locate required modules during the 
linkage edit. 


e Generating reports that list each public symbol, the mod- 
ule that defines it and all modules that reference it. 
Reports can cross-reference a single library or an entire 
program. 
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Plib86 Program Initiation 
a | 


The file PLIB86.EXE is required to execute Plib86. Like 
Plink86p/us, PlibB6 may be used interactively, with statement 
input included on the command line or with input inserted from a 


disk file: 
Interactive: PLIB86 «cr» 
Statements Included: PLIB86 [statements] «cr» 
Input from a File: PLIB86 @file.Ink «cr» 


Input formats and naming conventions are the same as 
Plink86p/us, but PlibB6 contains its own set of input statements. 
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Plib86 Input Examples 
eee 
The following examples show how the most-commonly-used 


Plib86 statements create and manipulate object library files. 


Create and Merge Libraries 
Place object modules and existing libraries in a new library file 


with the BUILD and FILE statements: 


BUILD TEST.LIB 
М1.ОВЈ, M2.0BJ, L3.LIB 


File 
This example creates a library file named TEST.LIB containing all 
modules in the files listed after FILE. input files can be single 


object modules or entire libraries. 


Update Existing Libraries 
Create a new library that merges new modules with all or part of 


the old library using BUILD, FILE and EXCLUDE: 


BUILD NEW.LIB 
M4, M5, TEST.LIB EXCLUDE M2 


FILE 
This example creates a library file named NEW.LIB containing M4, 


M5 and all modules from TEST.LIB except M2. 


Library Search 
Include only the library modules that are actually referenced by 
other input files with the LIBRARY statement: 


BUILD TEST.LIB 

FILE M1, M2 | 

LIBRARY L3.LIB і 
This creates а library file TEST.LIB that contains modules from М1 
and M2, and also any L3.LIB modules referenced by M1 and M2. 
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Plib86 Input Examples, Continued 
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Cross-Reference Listings 
Generate a cross-reference report with the LIST S statement to 
list symbols defined in each input module and all modules that 
reference them. 


LIST S 
FILE М1.ОВЈ, M2.OBJ, L3.LIB 


This creates a list of symbols that are defined in the input files 
М1.ОВЈ, M2.OBJ and L3.LIB. Each symbol is followed by the 
modules that refer to it. 


LIST S used with LIBRARY creates a cross-reference of an entire 
program: 


LIST S 
FILE M1, M2 
LIBRARY L3.LIB 


This report describes all modules from M1.OBJ and M2.OBJ, and 
any L3.LIB modules containing symbols that are referenced by 


M1 and M2. 


Extract a Single Library Module 
Extract a single module with the EXTRACT statement. EXTRACT 
creates an object module file containing the first module encoun- 
tered in the input files or the module specified by INCLUDE: 


EXTRACT TEST.OBJ 
FILE TEST.LIB INCLUDE M1 


This example creates an object file named TEST.OBJ that con- 
tains only the module M1 from TEST.LIB. | 
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Plib86 Input Examples, Continued 
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Extract an Entire Library 


Extract all modules from a library in a single operation with the 
EXPLODE statement. Modules extracted with EXPLODE are 
placed in individual disk files. All modules are extracted from the 
library except when INCLUDE or EXCLUDE is used: 


EXPLODE 
FILE TEST.LIB EXCLUDE M1 


This example extracts all modules from TEST.LIB except M1. 
Each module is placed in a disk file named as the module name 
and file type .OBJ. 


Page 11-8 Plink86 plus User Manual 


C еу 


Plib86 Input Statements 


PlibB6 statements include the following: 


STATEMENT PURPOSE 


Changes the default method for naming 
modules in object files (but not libraries) 
that are input to Plib86. 


Causes Plib86 to terminate with a fatal 
error if it cannot find a requested object 
file or library. 


BLOCKS Used with BUILD to override the number 
of index blocks to build for the new 
library. 


Excludes all undefined symbols from the 
list of symbols included in the Plib86 
LIST report. 


Overrides the block size for the new 
library. 


BUILD Creates a new library using modules 
selected from the input files. 

EXCLUDE Specifies modules in the statement input 
to exclude from Plib86 processing. 


EXPLODE Extracts all or selected modules from a 
library file and copies them to individual 
disk files. 


EXTRACT Copies a single object module from a 
library file in the Plib86 input to a 
specified disk file. 


Defines object files and libraries for 
input to Plib86 for processing. 


CONTINUED 
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Plib86 Input Statements, Continued 


STATEMENT PURPOSE 


HEIGHT Changes the page height of the LIST 
reports to the specified number of lines. 


INCLUDE Allows inclusion of specific modules only 
for input to Plib86 processing. 


INTEL Causes BUILD to construct an Intel 
format index for the Plib86 library file 
instead of the default Microsoft format 


index. 


LIBRARY Defines libraries that Plib86 will search once 
for required library modules. 


LIST Generates the Plib86 modules report or 
the cross-referenced symbols report 
for the input object files being 


processed. 


LOWERCASE | Forces Plib86 to translate all identifiers 
and symbols to lower case. 


MODRENAME | Forces all modules to use the name of 
their object file instead of the name 
given by the compiler or assembler. 


Inhibits the Plib86 time-stamp. 


Suppresses automatic library search 
requests during cross-reference 
generation. 


NODATE 


NODEFLIB 


Excludes specified symbols from the 
Plib86 library index. 


CONTINUED 
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Plib86 Input Statements, Continued 
ЕДШ | 


NWIDTH Changes the width of symbol and 
module names that are printed on the 
LIST reports to the specified number 
of characters. 


SEARCH Inputs library files for Plib86 processing 
and uses a multiple search method to 
find undefined symbols. 


TINY Removes all object records containing 
debugging information as modules are 
extracted, exploded or copied into a 
library. 

UPPERCASE Forces Plib86 to translate all identifiers 
and symbols to upper case. 

VERBOSE Displays a status line at the console 
during processing to identify the task 
Plib86 is currently executing. 

WIDTH Sets the page width of the LIST reports 
to the specified number of characters 
per line. 


Each statement is described in detail in this chapter. 
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AS 
as | 


Type: 
Plib86 Statement Key Word 


Purpose: 
Changes the default method for naming modules in object files 
(but not libraries) that are input to Plib86. 


Syntax: 
AS «modulename» 


Background: 
By default, Plib86 uses the module name given by the compiler or 


assembler. AS overrides this to specify a different name for a 


single module. 


Note: 
Refer also to the MODRENAME statement, which gives all mod- 


ules the name of their object file. 


Example: 
file TEST AS COS 


Names the module in TEST as COS instead of the default TEST. 
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BATCH 
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Туре: 

Plib86 Statement Key Word 


Purpose: 


Causes Plib86 to terminate with a fatal error if it cannot find a 
requested object file or library. 


Syntax: 
BATCH 


Background: 


Normally, Plib86 prompts the operator to enter the name of a disk 
drive or directory path name if it cannot find a requested object 
file or library. j 


BATCH causes Plib86 to terminate instead. This is useful if the 
program is being run from within a batch file and no operator is 
available to respond to the prompt. 


Example: 
search FORTRAN.LIB BATCH 


Instructs Plib86 to terminate if it cannot find FORTRAN.LIB. 
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BLOCKS | 


Туре: 
Plib86 Statement Key Word 


Purpose: 


Used with BUILD to specify the number of index blocks to build for 
the new library. 


Syntax: 
BLOCKS <number of blocks> 


Background: 


The Microsoft library index consists of a prime number of hash 
blocks. Plib86 normally selects the index size by calculating the 
amount of space required to fit everything in and adding ten per 
cent. 


The: BLOCKS statement overrides this calculation by using the 
number of blocks specified. The maximum number of library 
index blocks is 997. 


If the argument is not a prime number, Plib86 rounds it up to the 
next prime number. If the specified blocks are not enough for all 
symbols to fit in the index, warning messages are displayed 
during processing. 


Note: 


The BLOCKS statement only works when the BUILD statement is 
also used. 


Example: 


build TEST.LIB BLOCKS 7 


Forces Plib86 to use seven blocks for the library TEST.LIB. 
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BRIEF 
_ аша шш S анан 
Туре: 

Plib86 Statement Key Word 


Purpose: 
Excludes all undefined symbols from the list of symbols included 
in the Plib86 LIST report. 


Syntax: 
BRIEF 


Background: 
The BRIEF statement is especially useful with the LIST S report, 
which can be quite lengthy if it includes undefined symbols from 
libraries that were not searched when the report was created. 
BRIEF excludes these symbols from the report. 


Example: 
list s BRIEF 


Excludes all undefined symbols from the LIST S report. 
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BSIZE 
Se ee | 


Type: 
PlibB6 Statement Key Word 


Purpose: 
Overrides the block size for Microsoft format object libraries. 


Syntax: 
BSIZE <block size> 


Background: 


Normally, each module within a library is synchronized to start at 
the next available 512-byte disk block within the library file. On 
average, this wastes 256 bytes between each module. 


The BSIZE statement may be used to reduce the block size. 
However, the total size of the library file is limited to 65536 bytes 
multiplied by the selected block size. 

Note: 


Old versions of Microsoft LINK cannot handle libraries whose 
block size is not 512 bytes. 


Example: 


build TEST.LIB blocks 7 BSIZE 10h 


Forces Plib86 to use seven blocks for the library TEST.LIB and 
causes a block size of one 16-byte paragraph. Total library size is 
limited to one megabyte. 
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BUILD 
— SS 
Type: 

Plib86 Statement Key Word 


Purpose: 
Creates a new library using modules selected from the input files. 


Syntax: 
BUILD <filename> 


Background: 
BUILD creates new libraries by using selected modules from the 
input file. BUILD cannot be used at the same time as EXTRACT 
or EXPLODE. The filename of the library to create is included as 
an argument to BUILD. The file type defaults to .LIB if not 
specified. 


All modules in the input files are merged into a single library file 
by BUILD except when the INCLUDE and EXCLUDE statements 
list specific modules to include or exclude. The library index is 
created after all modules have been output. 


Examples: 
BUILD test file F1, F2 


Creates a library named TEST.LIB using the files F1 and F2 as 


input. F1 and F2 might contain single modules or entire libraries 
of modules. 


BUILD test file M1, TEST.OLD exclude M1 


Creates a library named TEST.LIB using a new module M1 from 
the file M1.OBJ and all modules from TEST.OLD except M1. 
(Note: TEST.LIB was renamed as TEST.OLD prior to executing 
this example.) 
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EXCLUDE | 
| 
Type: 

Plib86 Statement Key Word 


Purpose: 
Specifies modules in the statement input to exclude from Plib86 
processing. 

Syntax: 
EXCLUDE <modulename>[, <modulename> ...] 


Background: 


Normally, all modules in the specified input files are included in 
Plib86 processing. EXCLUDE allows you to exclude specified 
modules from Plib86 processing. 


EXCLUDE is only valid for the FILE, LIBRARY or SEARCH file 
immediately preceding it. To add a file after an EXCLUDE state- f 
ment, you must use another FILE, LIBRARY or SEARCH state- { 
ment. 


Note: 


Refer also to the INCLUDE statement, which includes specified 
modules only for Plib86 processing. 


Examples: 


file TEST.OBJ, F1 EXCLUDE SORT, COS 


Makes all modules from TEST.OBJ available for input to Plib86, 
but excludes the modules named SORT and COS in the F1.OBJ 
input file from selection by Plib86. 


file TEST.OBJ, F1 EXCLUDE SORT file COS 


Excludes the module named SORT as before but inputs COS. E 
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EXPLODE 
LLL 
Type: 

PlibB6 Statement Key Word 


Purpose: 


Extracts all or selected modules from a library file and copies 
them to individual disk files. 


Syntax: 
EXPLODE 


Background: 


EXPLODE does not allow input of file names for object files it 
creates. Each module is copied to a file named with the name 
from the module and the file type .OBJ, overwriting any existing 
files with the same names. The input library is unchanged. 


If an exploded module has been time-stamped, the new object 
file uses the module's time-stamp as its creation date instead of 
the current system date. The NODATE statement causes the new 
object file to use the current system date as its creation date. 


Note: 


Refer also to the EXTRACT statement, which extracts a single 
module only. 


Examples: 
EXPLODE file F1.LIB 


Extracts all modules from F1.LIB and copies them in disk files 
named with the module name and file type .OBJ. 


EXPLODE file F1.LIB include COS, SORT 


Copies the modules COS and SORT only from F1.LIB to the disk 
files COS.OBJ and SORT.OBJ. 
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EXTRACT 
OO eee 
Type: 

Plib86 Statement Key Word 


Purpose: 


Copies a single object module from a library file in the Plib86 input 
to a specified disk file. 


Syntax: 
EXTRACT <filename> 


Background: 
By default, the first module found in the input files is extracted 
and placed in a separate disk file by EXTRACT. The INCLUDE 
statement can specify a module to extract. EXTRACT cannot be 
used at the same time as the BUILD statement. 


The object file created by EXTRACT may be given any name. The 
file type defaults to .OBJ for the new object file if not specified. 
The extracted module name remains the same. 


If an extracted module is time-stamped, the new object file uses 
the module’s time-stamp as its creation date instead of using the 
current system date. If the NODATE statement is used, the new 
file uses the current system date as its creation date. 


Note: 
Refer also to the EXPLODE statement, which extracts all or 
selected modules in a single operation. 


Example: 
EXTRACT TEST file F1 include COS 


Copies the module COS from the input file F1.OBJ to TEST.OBJ. 


anu 
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FILE 


Type: 
Plib86 Statement Key Word 


Purpose: 


Defines object files and libraries for input to Plib86 for processing. 


Syntax: 


FILE «filename»[, «filename», ...] 


Background: 


All modules contained in files that are listed as input files in the 
FILE statement are included for PlibB6 processing, except when 
the INCLUDE or EXCLUDE statements identify specific modules 
for inclusion or exclusion. If no output is requested, Plib86 simply 
reads the input modules and reports any errors. 


If a file requested by the FILE statement cannot be found, Plib86 
checks for a DOS SET string named 'OBJ'. The value of the string 
is assumed to be one or more directory path names in the 
standard DOS PATH command format. 


Typically, this string is set up to refer to a directory that contains 
libraries and other commonly used object files that are available 
for processing. Plib86 prepends the path names to the requested 
object file name, adds the separator character 'N' between the 
path and file names and searches again for the file. 


For example, if SET OBJ=\OBJECT is entered before Plib86 is 
executed and the file TEST.OBJ is being searched for, Plib86 
looks for NOBJECTNTEST.OBJ. 


If the input file still cannot be found, Plib86 prompts for entry of a 
path name to prepend to the requested file name and searches 
again. This also occurs if no suitable DOS SET string exists. To 
override the prompt, use the BATCH command. 
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FILE, Continued 
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Examples: 
FILE TEST.OBJ 


Identifies TEST.OBJ as an input object file whose modules will be 
included іп Plib86 processing. 


FILE A, B 


Identifies A.OBJ and B.OBJ, as input object files whose modules | 
will be included іп Plib86 processing. | 


FILE F1.LIB include COS, SORT 


Inputs the modules COS and SORT only from the file F1.LIB for | 
Plib86 processing. | 
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HEIGHT 
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Type: 
PlibB6 Statement Key Word 


Purpose: 
Changes the page height of the LIST reports to the specified 
number of lines. 


Syntax: 
HEIGHT «number of lines» 


Background: 
LIST reports default to 66 lines per page when HEIGHT is not 


used. 


Note: 
Plib86 outputs a form-feed character when a report is to continue 


printing on the next page. 


Example: 
list m HEIGHT 88 


Creates a list of modules on an 88 line page. 
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Type: 

Plib86 Statement Key Word 
Purpose: 


Allows inclusion of specific modules only for input to Plib86 
processing. 


Syntax: 


INCLUDE <modulename>[, <modulename>, ...] 


Background: 


Normally, all modules in the input file are available for inclusion in 
Plib86 processing. INCLUDE overrides this so only the specified 
modules are considered for processing. INCLUDE is only valid for 
the FILE, LIBRARY or SEARCH file immediately preceding it. 


Note: 


Refer also to the EXCLUDE statement, which allows exclusion of : 
specified modules from Plib86 processing. " 


Ехатріе: | 
file TEST.OBJ, F1 INCLUDE SORT, COS | 


Makes all modules from TEST.OBJ available for input to Plib86, 


but allows only the modules named SORT and COS from the input 
file F1.OBJ. 
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Type: 
Plib86 Statement Key Word 


Purpose: 
Causes BUILD to construct an Intel format index for the Plib86 
library file instead of the default Microsoft format index. 


Syntax: 
INTEL 


Background: 
The INTEL statement is required to create libraries with the Intel 


format index. The LOWERCASE statement may also be required 
for some compilers using the INTEL format. ` 


Example: 
build TEST file f1, f2 INTEL 


Creates a library name TEST.LIB in the Intel format. 
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LIBRARY 
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Type: 

Plib86 Statement Key Word 


Purpose: 


Defines libraries that Plib86 will search for required library mod- 
ules. 


Syntax: 
LIBRARY <libraryname>[, <libraryname>, ...] 


Background: 
Not all modules are selected for input from the specified library. 
LIBRARY selects only the modules that are required for Plib86 
processing. 


The library modules that are selected for input define symbols 
that were previously declared external and are currently unde- 
fined in the processed modules. This selective culling of the 
library file is called a library search. 


Note: 
.LIB is the default file type unless otherwise specified. 


Example: 
LIBRARY a.lib, b.lib 


Identifies A.LIB and B.LIB as input library files whose modules may 
be searched and input to Plib86. 


Note: n 
LIBRARY will search through a library file once. Refer to the : 


SEARCH command for multiple search capabilities, required for 
several libraries which refer to each other. 
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Plib86 Statement Key Word 


Purpose: 


Generates the Plib86 modules report or the cross-referenced 
symbols report for the input object files being processed. 


Syntax: 
LIST [= «filename»] [M], [S] 


Background: 


LIST reports are written to the console by default. Optionally, 
reports may be written to a disk file or to a device such as a 
printer by including the "z" argument and identifying the filename 
or device. 


LIST M provides an alphabetical list of all input modules, with 
symbols defined within each also listed. 


LIST S provides an alphabetical list of all public and external 
symbols in the input modules. Each symbol is followed by the 
name of the module that defines it (in parentheses) and by a list 
of ali modules that reference it. The defining module is left blank 
when a symbol is not defined by any module. 


Example: 


LIST = 1051.181 s 
file f1.obj, f2.0bj library f3.lib 


Lists each symbol іп F1.OBJ and F2.OBJ in a disk file named 
TEST.LST. Also listed are symbols in modules from F3.LIB re- 
quired by F1.OBJ and F2.OBJ. Included with each symbol are its 
defining module and all modules that access it. 
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LOWERCASE 
Se ыыы ыш 
Туре: 

Plib86 Statement Key Word 


Purpose: 


Forces Plib86 to translate all identifiers and symbols to lower 
case. 


Syntax: 
LOWERCASE 


Background: 


By default Plib86 uses the original upper or lower case for all 
identifiers and symbol names. LOWERCASE overrides this default 
and forces all identifiers and symbol names to lower case. 


Example: 
plib86 LOWERCASE @test «cr» 


Loads the link file TEST.LNK and translates all identifiers and 
symbols to lower case. 
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en 


Type: 
Plib86 Statement Key Word 


Purpose: 
Forces all modules to use the name of their object file instead of 
the name given by the compiler or assembler. 


Syntax: 
MODRENAME 


Background: 
Normally, each module is given a name by the compiler or 
assembler and this name is used бу Plib86. MODRENAME causes 


modules to use the name of their object file instead. 


Note: 
Refer also to the AS statement, which allows you to specify a 


different name for a single module. 


Example: 
build test.lib 


MODRENAME 
file M1, M2 
Creates a library named TEST.LIB using M1 and M2 as input. 
Modules are given the name of their object file (M1 or M2) 


instead of the compiler-generated name. 
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NODATE 
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Туре: 

Plib86 Statement Key Word 


Purpose: 
Inhibits the Plib86 time-stamp. 


Syntax: 
NODATE 


Background: 


NODATE overrides the method Plib86 uses to time-stamp each 
module that is placed into an object library. The time-stamp is a 
comment record that is stripped when the module is extracted. 


Normally, each module is time-stamped with the creation date of 
its object file when it is placed into a library. When a module is 
later extracted, the new object file uses the module's time- 
stamp as its creation date instead of using the current system 
date. 


NODATE inhibits the time-stamp, causing the new object file to 
use the current system date as its creation date when a module is 
extracted. 


Examples: 
build test file f1, f2 NODATE 


Creates a library named TEST.LIB from the object files F1.OBJ 
and F2.OBJ with the current system date as the time-stamp 
instead of using the creation date from F1 and F2. { 


explode file test.lib NODATE и 


Extracts all modules in TEST.LIB and copies them to individual 
disk files with the current system date as the file creation date. 
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NODEFLIB 
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Type: 

PlibB6 Statement Key Word 


Purpose: 


Suppresses automatic library search requests during cross- 
reference generation. 


Syntax: 
NODEFLIB 


Background: 
Automatic library search requests are imbedded in object files by 
Microsoft and other compilers. Plib86 normally honors these 
requests only during cross-reference generation. NODEFLIB 
inhibits these requests under all circumstances. 


Example: 


list s 

NODEFLIB 

file M1, M2 
library fortran.lib 


Describes all modules from M1 and M2 but suppresses automatic 
library search requests. 
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ЕЕЕ НЫЛА БАДЫ 
Туре: 
Plib86 Statement Key Word 


Purpose: 
Excludes specified symbols from the Plib86 library index. 


Syntax: 
NOINDEX «symbolname»[, <symbolname> ...] 


Background: 


Normally, all public symbols are inserted into the library index. 
When duplicate symbols are found, the first module that defines 
the symbol is used and the duplicates are ignored. 


NOINDEX overrides this process by excluding specified symbols 
from the library index. For example, if a library is created with 
several versions of the same module (such as device drivers), 
NOINDEX can eliminate the resulting duplicate symbols from the 
index. 


Since the Microsoft library index format already contains an entry 
for each module (module name followed by an exclamation 
point), duplicate symbols may be excluded by NOINDEX. The 
module name and exclamation point are then used instead to 
reference the module. For both Microsoft and Intel format librar- 
ies, insert a unique "dummy" symbol in each module and use 
that symbol to reference the module. 


Example: 
build test file F1, F2 NOINDEX S1, S2 


Builds the library TEST.LIB with the object files F1 and F2, but 
excludes the symbols S1 and S2 from the index. 
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Шеше... дада ады ады тылын 
Туре: 

Plib86 Statement Key Word 


Purpose: 


Changes the width of symbol and module names that are printed 
on the LIST reports to the specified number of characters. 


Syntax: 
NWIDTH <number of characters> 


Background: 


Symbol and module names default to twelve characters maxi- 
mum for the LIST reports when NWIDTH is not used. NWIDTH 
affects only the LIST reports. It does not affect the actual symbol 
names in the files. When a name exceeds the specified width, it 
is truncated to make it fit in the report column. 


Note: 
NWIDTH changes the number of columns that fit on a page. 


Example: 
list m NWIDTH 20 


Creates a list of modules with a 20-character maximum symbol 
and module name width. 
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SEARCH 
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Type: 

Plib86 Statement Key Word 


Purpose: 


Inputs library files for Plib86 processing and uses a multiple 
search method to find undefined symbols. 


Syntax: 
SEARCH «libraryname»[, <libraryname>, ...] 


Background: 


Plib86 uses the library search to select only the modules that 
define public symbols required by other modules that have 
already been processed. 


SEARCH defines libraries for input to Plib86 processing the same 
as the LIBRARY statement, but causes Plib86 to make multiple 
passes through the specified library files if undefined symbols 
remain after the files have been read. 


This is useful for situations where all required modules cannot be 
extracted from the library in one pass, such as when two libraries 
each refer to symbols defined in the other. 

Note: 
.LIB is the default file type unless otherwise specified. 


Example: 
SEARCH L1, L2 


Searches L1.LIB and L2.LIB modules as required until all public 
symbol definitions that can be located are found. 
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Type: 
Plib86 Statement Key Word 


Purpose: 


Removes all object records containing debugging information as 
modules are extracted, exploded or copied into a library. 


Syntax: 
TINY 


Background: 
Debugging information removed by TINY includes line numbers, 
local symbols, type definitions, comments, debugging symbols 
and block definitions. 


TINY may reduce the size of the library and also makes it harder 
for software pirates to figure out how the software works because | 
there is less compiler information included in library modules. | 


Ехагпр!е: 
build TEST file F1, F2 TINY 


Creates a library named TEST.LIB from F1.OBJ and F2.OBJ but | 
strips all debugging information as the modules are placed in the | | 
new library. 
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UPPERCASE 
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Type: 


PlibB6 Statement Key Word 


Purpose: 
Forces Plib86 to translate all identifiers and symbols to upper 
case. 

Syntax: 
UPPERCASE 


Background: 


By default Plib86 uses the original upper or lower case for all 
identifiers and symbol names. UPPERCASE overrides this default 
and forces all identifiers and symbol names to upper case. 


Example: 
plib86 UPPERCASE @test «cr» 


Loads the link file TEST.LNK and translates all identifiers and 
symbols to upper case. 
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Type: 
Plib86 Statement Key Word 


Purpose: 
Displays a status line at the console during processing to identify 
the task Plib86 is currently executing. 

Syntax: 
VERBOSE 


Background: 


The VERBOSE statement slows down processing considerably. 
You may want to use it only as you are learning how to use Plib86 
or if you are having problems with a library. ` 


Note: 


This statement should not be used on a teletype-like terminal as 
it will continuously rewrite the same line. 


Example: 
build TEST file F1, F2 VERBOSE 


Creates the library TEST.LIB from Е1.ОВЈ and F2.0BJ and dis- 
plays the status line during processing. 


| 
| 
% 
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Type: 
Plib86 Statement Key Word 


Purpose: 
Sets the page width of the LIST reports to the specified number 


of characters per line. 


Syntax: 
WIDTH <number of characters> 


Background: 
LIST reports default to 80 characters per line when WIDTH is not 


used. 


Example: 
list m WIDTH 132 


Creates a list of modules with a line width of 132 characters. 


| 
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Plib86 Warning Messages 


NUMBER DESCRIPTION 


Duplicate symbol. 


There can only be one definition for each 
public symbol in the object modules being 
processed. Plib86 retains the first definition 
for use in library reports and in the library 
index. The duplicate symbol! definition is 
ignored. 


Checksum error. 


Each record in an object file contains a 
check field for validation purposes. This 
message indicates the checksum was bad, 
but processing continues. This message 

is inhibited after it has been displayed a 
few times. If the file is really smashed, a 
fatal error will probably occur soon after 
this message is displayed. Sometimes this 
error is displayed because the object file 
was patched on disk but the checksum was 
not changed. Some compilers are 
somewhat sloppy about producing correct 
checksums. 


Record size error. 


Each record in an object file has a word 
giving the record size. This warning 
message indicates Plib86 has reached the 
end of the record and found the number 
of bytes processed is different from the 
specified size. The object file is probably 
smashed, but Plib86 attempts to continue 
reading it. 


No room in library index. 


The Microsoft library index being created 
with the BUILD statement is too small to 
contain all symbols. This should only occur 
if the BLOCK statement was previously 
used to limit the size of the index. 
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Plib86 Error Messages 


| NUMBER | DESCRIPTION 


@ files nested too deeply. 


‘@' files are nested more than three layers 
deep. This error can also be caused by a 
loop іп the “@” file references. 


Can't read @ file. 


A disk error was encountered while reading 
an '(Q file. Try rebuilding the file. 


Missing @ file. 
Plib86 cannot locate the requested @ file. 


Input item too large. 


The item given for input at this point 
exceeds 64 characters. 


Invalid digit. 
The number contains a digit that is not 
valid for the radix being used (1A is not a 


valid decimal number, etc.). 


Invalid file name. 


The specified file name is not a valid file 
name under DOS. 


Expecting statement. 


A statement was expected at this point in 
the input. 


Can't use INCLUDE with EXCLUDE. 


The INCLUDE and EXCLUDE statements 
cannot refer to the same file. 


Invalid value. 
The maximum BSIZE command value is 
Oxffff. 


CONTINUED 
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Expecting ID. 
An identifier (section, module, segment or 
symbol! name) was expected at this point 

in the input. 


Expecting value. 
A numeric value was expected at this point 
in the input. 


No files given to process. 

At least one FILE statement must appear 
to specify the input file. 
Can't use BUILD with EXTRACT. 


The BUILD and EXTRACT statements 
cannot be used simultaneously. You must 
run Plib86 twice to perform these functions. 


Can't create work file. 


There is no space in the disk directory to 
create the work file. 


Can't write work file. 
An МО error occurred while writing the work 
ile. 
Can't read work file. 


An І/О error occurred while reading the 
work file. 


Can't position work file. 


An МО error occurred while positioning the 
work file. 


Too many objects in program. 
There are more than 32,000 objects 
(symbols, segments, groups, etc.) defined 
in the library and it is too large for Plib86 
to handle. 


CONTINUED 
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Plib86 Error Messages, Continued 


DESCRIPTION 


Premature end of file. 


The end of the indicated file was reached 
unexpectedly. 


Read error. 
A fatal read error was found in the input 
object file. 


Can’t find specified file. 


The input file cannot be located and the 
program is being terminated. This message 
appears after Plib86 has prompted for 

entry of a file name prefix and the operator 
has elected to terminate the linkage edit 
instead. When the BATCH statement is 
used, this message is issued immediately 
without prompting when the object file 
cannot be located. 


Can’t create file. 


The output file cannot be created. The 
disk directory may be full or the disk may 
be write-protected. 


Output file size too large. 


The modules will not fit into the library. 
Correct this by creating two or more 
smaller libraries. 


Write error in file. 


The disk may be full or write-protected, 
or a hardware error may have occurred. 


Can't read file. 

A fatal disk read error was encountered in 
the ouput file. An irrecoverable hardware 
error has occurred. 
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Plib86 Error Messages, Continued 


Can't close file. 
The disk is probably write-protected or a 
hardware error may have occurred. 


Can't create report file. 
The disk directory is probably full, or the 
disk is write-protected. 


Too many symbols in library. 

Plib86 cannot place all required symbols 

in the library index. Correct this by creating 
two or more smaller libraries. 


No modules selected. 

No modules were selected by 

FILE, LIBRARY, SEARCH, INCLUDE or 
EXCLUDE for the output field created by 
BUILD or EXTRACT. 


Not enough memory. 
There is not enough available memory for 
Plib86 to execute. 


Record too large. 
No single record may be larger than 1,024 
bytes. 


Index number out of range. 

Forward references are not allowed within 
the object module. This error occurs 
when a record refers to a segment that 
has not yet been defined. 


Invalid Intel format library file. 
| Plib86 expects its input libraries to conform 
| to the Intel/Microsoft formats. 
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Diagnostic Error Messages 


| 201 | No NeedRead buffers in NRNEW. 


Seek error while writing output file (attempt 
to seek past end of file). 
Sand Buffer pointers corrupted in REUSEBUFFER. 
ИТЕ Requested record size too large їп NEWREC. 


Requested block number out of range in 
GETBLOCK. 
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APPENDIX A - LINKAGE EDITOR CONCEPTS 


This appendix describes what linkage editors do and why today's 
software developer is required to use one when writing programs . 
for microcomputers. 


Modular Programming 


Typically, it is convenient (if not essential) to divide large pro- 
gramming jobs into smaller pieces called "modules" that can be 
individually edited and compiled. This is called "modular pro- 
gramming" because programs are organized into logical modules 
that are easier to maintain. Using a linkage editor to link together 
the program modules can save time because only the affected 
modules need recompiling when a change is made. The linkage 
process is generally faster than recompiling the program. 


Memory Management 


Microcomputer programmers are faced with the problem of fitting 
everything into available memory at the right time. Solving 
memory management problems can be more time-consuming 
than the actual application. Overlay linkers help minimize memory 
management problems by providing methods for swapping vari- 
ous components of the program in and out of memory as 
required during execution. Since portions of the code share the 
same memory locations, the total memory requirement of the 
program can be greatly reduced. 


Object Files 
Most compilers output an intermediate form of the generated 
code in an object file. This file contains information that is used by 
the linkage editor to combine it with other modules. The compiler 
relies on the linkage editor to transform the object file into an 
executable file which the operating system may load. 


Appendix A — Linkage Editor Concepts A-1 


Library Files 


Compilers are usually sold with a run-time support library whose 
modules are required while the program executes. These mod- 
ules contain math functions and other features that are not 
supported directly by the computer hardware and are imple- 
mented as procedure calls. The compiler library contains mod- 
ules that support the high-level features of the language, such as 
the formatted output in FORTRAN. 


General software products are also sold as libraries. For example, 
a set of database management routines could be combined with | 
application modules by the linkage editor to produce a complete 
system. In addition to these purchased libraries, most program- 
mers build their own library of general purpose routines that can 
be hooked in by the linkage editor when they are needed. This 
eliminates the need for resolving common programming prob- 
lems again and again. 


Library Search and Index 


Linkage editors typically have special facilities for handling librar- 
ies. TO save memory space, only those modules in the library 
that are actually required by the program are linked in. To save 
time, a library index is used instead of a sequential search 
through the library to find required modules. 
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Disk Storage 


Some overlay linkers store sections of a program on disk by 
putting a section into a separate file. This wastes space in the 
disk directory and requires a directory search whenever a section 
is loaded into memory. It also slows execution and clutters the 
disk with a lot of files. Despite these problems, the separate file 
approach has advantages because components of a product can 
be easily isolated. For example, overlay files may be packaged 
f on separate disks if the application is too large to fit on a single 


< disk or if the overlays contain separately-sold program functions. 
Ü Plink86p/us allows a programmer to arbitrarily group program 
i sections into as many (or few) output files as desired for a 


| specific situation. This storage method allows the programmer to 
retain the packaging advantages of the separate file method while 
controlling its speed of execution and disk management prob- 
lems. 


Linking Programs 


Some linkage editors allow linking a program in pieces. This 

eliminates the need for relinking the entire program if only one 

section has to be changed. However, symbols in an overlay are 

) usually not visible outside of the overlay with this method and the 
entire system must still be relinked when a resident portion of the 
program is modified. 


Plink86p/us requires that the entire program be linked each time, 
even if the program is being loaded into more than one output 
file. The compensating advantage with this method is that all 
public symbols are visible to all parts of the program with 
Plink86p/us. Plink86p/us uses all available memory to hold I/O 
buffers and the description of the program being linked rather 
than the actual program. It pages program descriptions to disk if 
there is not enough free memory to hold them. 
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Link-time may be decreased by splitting the program into several 

smaller programs that are linked separately and chained together 

by the operating system or executed from a batch file. Another 

trick is to merge together object files that are not currently being 

developed. Link-time is also greatly decreased by increasing the 

number of DOS buffers in CONFIG.SYS. "Buffers-30" provides > 
optimum performance on PC-AT-type hardware. 


Source Modules 


Many overlay linkers require explicit calls to the overlay manager 
in the source program. This means the module cannot be put into | 
different overlay structures without changing the calls and recom- 

piling the program. This method makes it difficult for the pro- 

grammer to visualize the final overlay structure because the 

information describing it is scattered throughout the program 

source code. 


Plink86p/us requires no changes to the source program modules. 
Instead, it offers an overlay description language that allows you 
to specify the overlay structure in one place at link-time rather 
than compile-time. 


Two-Pass Editing 


Plink86p/us reads each input file twice during the linkage edit. The 
first pass determines which modules to load and allocates seg- 
ment addresses. The second pass creates the output file. This 
insures that full information about all modules is available before 
the output file is created and also provides greater flexibility for 
assigning memory addresses. 
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APPENDIX B — INTEL 8086 CONCEPTS 


ЕЕЕ ooo Ee ы 
This appendix provides a summary of Intel 8086 basic addressing 
mechanisms that are important to the linkage edit process. For a 
comprehensive discussion of these and other Intel 8086 con- 
cepts, refer to one of the following Intel Corporation publications: 


9 iAPX 86/88, 186/188 User's Manual and Programmer's { 
Reference, #210910. 


н o ASM86 Assembly Language Reference Manual, #121703. 


ғ Addressing 


Intel 8086 addressing is based on a 16-bit address that can 
address up to 1 Megabyte. Each segment register may access 
64kB at one time, DOS manages up to 640 kB. To access a full 
megabyte of memory, four segment registers are provided that 
each effectively address a 20-bit memory area. Even though the 
program can only access four 64kB chunks of memory at any 
given moment, the segment registers can be moved around to 
access the entire address space by reloading the registers. 


5D—————— 


The segment registers (CS, DS, SS and ES) are actually only 
16-bits long, but the CPU adds four zero bits to the end, 
effectively producing a 20-bit address. Therefore, one megabyte 
can be addressed (16 bytes x 64kB). The 16-bit addresses used 
by most instructions are treated as an offset to one of the 
segment registers, 


Intel addresses are given in the form of two 4-digit base-16 
numbers, separated by a colon. The first number gives the 
paragraph address and the second number gives the offset from 

that paragraph. For example,100:15 and 101:5 are two Intel i 
format addresses representing location 1015, since the first is 
1000 plus 15 and the second is 1010 plus 5. 
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more than 64kB of code, although each logical segment must be 
less than 64kB in size. 


At load-time, DOS relocates the program and adds the para- 
graph address where the program was loaded to the segment 
addresses that are contained in the program. The Plink86p/us 
overlay loader does the same thing when overlays are loaded. 
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Format Structure 
In theory, each machine location could be represented by a 
number of base:offset pairs. Because of this, the linkage editor 
must know the paragraph address that will be used as a base 
whenever a memory address is needed. To provide this informa- 
tion, the Inte! object module format organizes code into public 
and private segments and groups and classes. 

Public Segments 
Public segments are segments that can be combined with other 
segments of the same name. Public segments are concatenated 
to occupy adjacent locations in memory. A combined segment 
may be accessed by putting its paragraph address into a seg- 
ment register, and using another register for the offset value. The 
size is the sum of the original segment sizes. 
Plink86p/us combines logical segments when instructed to do so, 
but not if they are in different sections. Plink86p/us assumes the 
address is the location of the segment that is lowest in memory. 
Only one entry is listed in the map for a public segment within a 
section, even if more than one module defined it. 

Private Segments 
Private segments cannot be combined. They are usually ad- 
dressed by setting a segment register to the front. The 8086 has 
long call and long jump instructions that set the CS segment 
register and change the execution address in IP. 
Many DOS compilers output a private segment for the module 
code and use the long jumps and calls to set the CS register to 
the front of the called segment. This allows programs to have 


Groups 


A group, like a public segment, is a way to define a collection of 
segments that will all be accessed by the same segment register. 


The address contained in the segment register will be the address 
of the segment with the lowest memory location within the group. 
If the end of the highest segment is within 64kB of the of the start 
of the lowest one, any of the segments may be addressed by a 
16-bit offset. A valid group must be within 64kB. 


Many compilers collect the data segment of the program into a 
single group called DGROUP. The DS segment register is set to 
point to DGROUP when the program begins and is left there. The 
compiler is then limited to creating programs with no more than 
64kB of data area. The advantage of this method is not having to 
generate code to load a segment register whenever a variable is 
to be accessed. 


Segments from different groups can be mixed together in the 
same section, and segments from the same group can be 
distributed among several sections. Even though the segments of 
a group aren't adjacent in memory, the addressing will still work 
right if the entire set of segments resides within a 64K memory 
area. 


Plink86p/us does not attempt to move segments of a group from 
one place to another to put them within 64kB of another. It does 
issue warning messages if something cannot be addressed from 
the base address of the group. The Plink86p/us GROUP state- 
ment puts all segments of a specified group into a specified 
program section. 
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Class 


Another way to refer to a collection of segments is by a CLASS 
name. The class name imposes an ordering on the segments and 
provides a method for moving all member segments to a speci- 
fied location without naming all of them. A segment may be 
assigned to a class by the compiler or assembler. Public seg- 
ments must have the same class name to be combined. 


Where possible, Plink86p/us allocates members of the same 
class to adjacent areas of memory in the order the class names 
are given. Within a class, segments are ordered in the sequence 
the segment names are given. Typically, compilers use the class 
names to define for the linkage editor the order in which seg- 
ments should be allocated memory. The Plink86p/us CLASS 
statement can also be used to specify segment ordering. 


Note: 


Some compilers do not give print segments a class name. To 
specify those segments in Plib commands, any segment without 
class names are assigned to the class “NIL” defined by the 
linker. 


Overlay Names 


Intel also introduced the concept of an overlay name for each 
segment. The name is specified at compile-time. Plink86p/us 
provides other methods for specifying the overlay structure at 
link-time, so it ignores the Intel overlay name. 
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APPENDIX C - OVERLAY LOADER 


SSS a a a a RM | ” 
This appendix provides technical information about the 


p Plink86p/us overlay loader. None of the information provided here 3 
7 is necessary to use the overlay loader in the usual way. 


User Support Module 


Behavioral aspects of the overlay loader can be changed by $ 
modifying the overlay loader's user support module. Virtually all Y 
overlay loader modifications required to make your application : 
run more efficiently can be accomplished with minor changes in 
the support module. 


21 
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Source code for the standard support module used by OVER- 
LAY.LIB is included in the disk file OVUSERM.ASM in the OVERLAY 
directory on the Plink86p/us distribution disk. A simplified support 
module that may suffice for many applications is found in the disk 
file SAMPLE.ASM in the same directory. 


4 
* 
“ 
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The following types of modifications сап Бе made in 
OVUSERM.ASM: 


o Change the algorithm to search for overlay files. 
o Change the operator prompts and fatal error messages. 
o Change the path to search for overlays. 


o Set the VIANET switch to support the ViaNet network. The i 
default is to support NETBIOS-compatible networks. 


o Set the MULTICOPY switch to support multiple copies of a 1 
single executable file running over a network. Overlays 
are read in shared mode and then closed when MULTI- 
COPY is enabled. 


> 
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ә Add code to be called at the end of an overlay load re- 
quest, such as to force files to be closed or to track us- 
age statistics. The default is to do nothing, or if MULTI- 
COPY is enabled, to close open overlay files. 


e Customize the overlay loader’s fatal exit routine to make 
sure all files are closed. The default is to leave them 
open. 


Customizing the Support Module 


OVUSERM.ASM can be assembled with PASM. To customize how 
the overlay loader operates, modify and reassemble 
OVUSERM.ASM and then link it in to your application with the FILE 
statement or by using the Plib86 object librarian to construct a 
new OVERLAY.LIB containing your modified OVUSERM.ASM. 


All public symbols must be properly defined in the new module if | 
it is input with the FILE statement. If not, the standard OVUSERM 
module will be loaded from OVERLAY.LIB. The OVERLAY state- 

ment must also be included in the statement input if the FILE 

statement is used here. For example, you would add “OVERLAY 

PROG, OVLOADER" to your Plink86p/us input if the compiler you 

are using places code segments in class “PROG”. 


Otherwise, your OVUSERM code segment will get moved to the 
end of the program instead of being combined with the other 
overlay loader segments in the ROOT section. The linker assumes 
only the first class it sees will be marked as overlayable, and the 
overlay loader modules have their own unique class name. 


The alternative method for linking a customized OVUSERM mod- 
ule into an application is to use Plib86 to construct a new 
OVERLAY.LIB that includes your modified OVUSERM.OBJ. This 
avoids the previous problem because the linker knows that all 
modules from OVERLAY.LIB should be placed in the root. 


To construct a new OVERLAY.LIB, use the OVERLAY.LNK file in 
the OVERLAY directory on the Plink86p/us distribution disk. This 
file rebuilds OVERLAY.LIB. 


PLIB86 @OVERLAY.LNK 


ps2 Appendix C - Overlay Loader 


2 CN 


Reload Stack Manipulation 


OVERLAY.LIB includes routines which save and restore the over- 
lay context, as well as the reloading stack. This allows you to 
execute a C longjmp into an overlay that is not currently in 
memory, in a reloading program. Some stringent restrictions 
apply: 


1. Both $OVSAVE and $OVRESTORE must be called as far 
routines, Call $OVSAVE before calling setimp, and $OV- 
RESTORE before calling longjmp. - 


For С programs, place the following lines in your link file: 
(C does not allow the dollar sign in identifiers) 


define ovsave = $OVSAVE 
define ovrestore = $OVRESTORE 


2. $OVSAVE must be called inline with the call to setjmp. 
Call $OVSAVE immediately before calling setjmp. 


3. $OVSAVE, $OVRESTORE, setjmp, and longjmp must not 
be vectored. Include in your link file the line 


never $OVSAVE, $OVRESTORE, setjmp, longjmp 


4. $OVRESTORE must be called immediately before the call 
to longjmp. In addition, you must ensure that the call to 
longjmp remains in memory after $OV/RESTORE returns 
(remember, $OV/RESTORE is loading the overlay context 
saved in $OVSAVE). The easiest way is to place the ] 
equivalent of the following code in your root, and replace 
your longjmp call with a call to longjmp: 


/* C routine to replace longjmp in reloading programs */ > 


void _longjmp(envbuf, code) 


jmp_buf *envbuf; /* buffer containing stack context */ 
int code; /* return code */ à | 
C ! | 
ovrestore(); /*restore the overlays */ 
longjmp(envbuf, code); /* jump into restored overlay */ 
( ) 
P 
i 
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$OVSAVE and $OVRESTORE will work for only one setjmp loca- 
tion. You must modify them if you wish to support multiple active 
longjmp targets. 


Source code for $OVSAVE and $OVRESTORE is included in the 
disk file OVSTACK.ASM in the OVERLAY directory on the 
Plink86p/us distribution disk. When modifications are made, 
OVERLAY.LIB must be rebuilt with the customized version of 
OVSTACK.ASM incorporated. 
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Overlay Loader Technical Information 


The following information is for those who wish to write their own 
overlay loader, a task that is not recommended unless there is no 
other way to accomplish your goals. You should exhaust all other 
possible solutions before attempting to write your own overlay 
loader. Source code for the overlay loader may be purchased by 
contacting Phoenix Technologies Ltd. 


Entry Points: The overlay loader is selected automatically at link 

time from a library of overlay loaders (OVERLAY.LIB). The main ( 
entry point symbol determines which overlay loader is selected. 

The main entry point is called by the symbol vectors. It is named 

"OVLYxx", where "xx" identifies the desired overlay loader: 


LOADER DESCRIPTION 


SOVLYM Standard overlay loader with overlay 
reloading. 

SOVLYV Standard overlay loader without overlay 
reloading. 


$OVLYMD Standard overlay loader with debugging 
messages. 

$OVLYS Standard overlay loader with memory 
caching. 

$OVLYSD Standard overlay loader with memory 
caching and debugging messages. 


Note: Pfix86p/us support code is in a separate OVERLAY.LIB 
module that is automatically linked in if the program 
contains overlays and the SYMTABLE statement is used ) 
to build a symbol table. ; 


- 
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Overlay Loader Symbols 
The overlay loader also contains the following symbols: 


ee eee eee DESCRIPTION 


Initialization entry point. This is always the 
starting address of the program when the 
overlay loader is present. It initializes 

the loader and then jumps to symbol 
$STRT$, the starting address of the 
application. 


Loads the overlay whose number is in CX. 
The application program may call this 
routine. If AH is non-zero and the over- 
lay cannot be found on disk, the loader 
returns to the application with the carry 
flag set. Otherwise, the program is 
terminated. 


The exit point from $OVLYxx for de- 
bugging. Since break-points cannot be 
set in the overlay before it is loaded, it is 
sometimes helpful to break at the address 
of this symbol. It points to the return 

back to the overlay vector jump instruction. 


The exit point from $LOAD$ for use by the 
Pfix86 plus debugger. 


$OVCLOSE Routine that closes the current overlay 
file (if one is open). All registers are 
preserved. The next time an overlay is 
required, the loader reopens the required 
file. This routine is useful for "terminate 
and stay resident" programs that contain 
overlays. It is invoked with a far call when 
required handles for the current program 
are about to become invalid. 


$OVSAVE Routine that saves the overlay context. 
SOVRESTORE| Routine that restores the overlay context. 
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Segmentation: The overlay loader addresses three segments: 
code, data, and $OVTB$. OVCODE and OVDATA are given a 
class name "OVLOADER". $OVTB$ is given the class name 
“LOADER”. This allows a small memory model program to move 
OVCODE and OVDATA out of the 64kB area. 


Overlay Tables: The linkage editor supplies a table in the ФОУТВ% 
common block that describes the overlays contained in the 
program for the overlay loader. $OVTB$ also contains the name 
of the file where the overlays are located. Overlays are numbered 
implicitly by order within the table (starting at one) and are 
organized into one or more tree structures via the father fields. 
The end of the overlay table is indicated by -1 in the OVFLGS 
field. All elements are 16-bit words unless otherwise specified. 


$OVTB$ contains the following information: For an assembly 
language header file of this information, see the outb.h file in the 
OVERLAY directory on the distribution disk. 


Base Offset: Gives the paragraph offset of the overlay loader 
from the front of the program. The loader can determine the 
paragraph address where the program was loaded by subtracting 
this offset from the current CS register at execution time. 


Loader Stack Size: Sets the stack size as the stack depth 
(number of calls) set with the RELOAD statement times six bytes 
per cal! (#calls x 6 bytes). Each return address is saved as if it 
were far. Stack size is zero if RELOAD is not included in the link. 


If caching is used: 


Configuration Flags: Consist of a word containing the following 
bits: 


Bit 0: Not used. 

Bit 1: LIM. Use expanded memory, Lotus-Intel-Microsoft 
format. 

Bit 2: Extended. Use extended memory. 

Bit 3: Regular. Use regular DOS memory. 
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Cache Size Fields: -1 is all that’s left, 0 is none. 


Minimum Cache size (regular memory) 
Maximum Cache size (regular memory) 
Minimum Cache size (extended memory) 
Maximum Cache size (extended memory) 
Minimum Cache size (expanded memory) 
Maximum Cache size (expanded memory) 


Convert Cache Units: Byte giving the number of shifts to convert 
cache units. 


Total Non-resident Size: Gives the total size of non-resident 
overlays and cache units. 


Number of Cache Units: Gives the number of cache units in 
64kB. 


End of Program Address: Gives the paragraph address of the 
end of the program in memory, which is past all overlays and 
data areas. The overlay loader sets a temporary stack at this 
location while initializing itself. 


Overlay Flags: 


ө bit O is in memory 
о bit 1 is preload 
ө bit 2 is resident 


Fixup Count: Contains the number of base fixup entries (4 bytes 
each) appearing at the front of the overlay on disk. This table is 
non-zero and rounded up to a page boundary followed by the 
actual overlay contents. 


Starting Memory Address: Gives the memory address as a 
paragraph address where the overlay should be loaded. 


Ending Memory Address: Gives the address of the end of the 
overlay in memory in the same format as the previous field. The 
loader must not load beyond this address. 
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File Name Offset: Gives the offset from the front of $OVTBS$ to 
the name of the file containing this overlay. These file names 
consist of a name and file type separated by a period and 
followed by a NULL. This is because there are no drive id's or 
path names. 


Disk Address: Double word giving the address of the overlay : 
within the selected disk file, stated as a paragraph offset from the 
front of the file. 


Disk Length: Gives the size of the overlay on disk in paragraphs. Г 


Í 
r 


2-- 


If caching is used: 


Cache Unit Offset: Gives the cache unit offset from the cache 
start. 


Ss --- 


| 


Index to More Recent Cached Overlay: Gives the index to the 
next most recently cached overlay. | 


Index to Less Recent Cached Overlay: Gives the index to the | 
next oldest cached overlay. 


The previous items beginning with “Overlay Flags” are repeated 
for each overlay in the program. The subtable is terminated by a 
-1 (OFFH) in the position where the overlay flags field would 
normally be found. 


File Names: Next are the overlay file names. Each name is an ! 
ASCII string terminated by a NULL. They аге pointed to by the | 
overlay entries that were previously described. There will only be 

one name unless Plink86p/us was instructed to use separate i 
overlay files. 


The final portion of $О\УТВ$ is made up of symbol vectors. ‚ 
Plink86p/us generates a symbol table name $OVVCS that points 
to this area. The vectors consist of a call to the $OVLYxx routine, 
a word giving the number of the overlay to load, and a jump to 
the true address of the routine supported by the vector. The call 
and jump instructions are long. The overlay loader never has to 
look at this portion of $OVTBS$. Plink86p/us automatically inserts | 
calls to $ОУТВ$ as the program is linked. 


.... 
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APPENDIX D - DEBUGGING TIPS 


Occasionally one must resort to machine language debugging to 
х find a difficult problem. The Pfix86p/us debugging program can 
) help here because it is aware of symbolic debugging information 
provided to it by Plink86p/us. 


If you are using a debugger other than Pfix86p/us, this appendix 
explains how to find things in memory and how to use the 
Plink86p/us memory maps for help in debugging. 


Addressing 


Except for symbols, addresses in the memory map are given as 
20-bit offsets from the start of the program. Symbols are given a 
two-part "paragraph:offset" Intel format address. When the 
program is executed, it is typically loaded at a non-zero address, 
so the program load address must be added to the segment 
addresses obtained from the memory map when using the 
debugger. 


For example, if the program was loaded at memory address 
8100, a segment or other 20-bit address appearing in the map as 
525 would correspond to a memory address of 8625 (81004525). 
A symbol appearing as 630:255 would be in memory at E40:255 
((810+630) :255), or E655 in long form. 


Short (16-bit) addresses are typically addressed as offsets from 
a particular group or segment. The offset as given on the 
memory map can be used if there is currently a segment register 
pointing to that group or segment. 


For example, a symbol in DGROUP with an address given as 
630:255 could be referenced in the debugger as DS:255 if DS is 
currently equal to the segment address of DGROUP. Watch out! 
Most DOS programs move the DS register to its assigned location 
sometime after program execution begins. 
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DOS loads the program into a single memory area whose address 
is not always obvious. One can look at the contents of the CS 
register for simple non-overlaid programs using short addresses. 
These programs are usually set up with the code area in front, 
and DOS sets CS to this location. 


However, if a program uses far calls, CS may not have been set 
to the front of the program. This is because DOS sets CS:IP to the 
starting addresses of the program at load time. 


The following trick works for all DOS programs to eliminate the 
problem described above: DOS always places a 256-byte seg- 
ment prefix at the front of the program when loading it into 
memory for execution. The DS and ES registers are initialized to 
point to the segment prefix. Therefore, the load address of the 
program may be determined by simply adding 100H (or 10H in 
paragraph form) to the value found in ES. You must do this 
before the program begins executing because these registers will 
probably be changed when execution begins. 


Debugging with Overlays 


The overlay loader initialization routine is always executed before 
the user program when the program has overlays. To get past 
this to the user program, set a break-point at symbol $STRT$. 
This dummy symbol created by Plink86p/us gives the address 
where program execution is to begin. $STRT$ can be found in the 
MAP G or MAP M reports. 


A break-point cannot be set in an overlay that is not currently in 
memory unless the Pfix86p/us debugger is being used. Pfix86p/us 
waits for the overlay to become resident and then automatically 
sets the requested break-point. However, a break-point can 
always be set at symbol $OVEX$. This symbol is іп the overlay 
loader at the point where the requested overlay has been loaded 
and the loader is about to return to the user program. 


Another trick is to find the call to the overlaid routine. The 
address called will be the overlay vector for the symbol (unless 
the NEVER statement was used). A break-point can be set at the 
jump following the call to the overlay loader. 
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APPENDIX E - ASSEMBLER TIPS 


Setting up proper addressing for assembly language programs 
generated with the Microsoft (or IBM) assembler is not always a 
simple task. The following should be considered when linking 
assembler programs: 


Class Names 
Make sure all segments are given a class name to insure that 
Plink86p/us is given a handle for grabbing segments. Use the 
CLASS statement if necessary. Otherwise, "NIL" is used. 


Alignment 
if public segments of the same name are given different align- 
ment factors, Plink86p/us uses the worst case alignment for the 
segment that is lowest in memory. The alignment given with the 
segment definition is used for the other segments. This was done 
for compatibility with Microsoft FORTRAN and Pascal. 


Contradictory Groups 
If some but not all versions of a public segment are in a group, 
Plink86p/us forces the other versions of the segment into the 
same group. If two public segments with the same name are said 
to be in two different groups, Plink86p/us issues a warning 
message and the program probably will not run without modifica- 


tion. 


Segment Ordering Bugs 
Many bugs can occur if the program classes and segments are 
not in their proper order. To check segment order, generate a 
MAP A report. If the segments have not combined properly, they 
will appear on the report in the wrong location. 


Ordering bugs frequently occur when assembly language mod- 
ules are combined with compiled code and the public assembler 
segments are not given the correct class and segment names. 
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A variation of this segment ordering problem occurs when a 
statement like “DGROUP GROUP DATA" is in assembly language 
and a data segment is not defined. The Microsoft (or IBM) 
assembler generates a dummy segment with no class name, and 
Plink86p/us usually issues a warning message that DGROUP is 
larger than 64kB. What really happens is the dummy DATA 
segment is more than 64kB away from the legitimate data 
segments and cannot be accessed. 


Another bug can occur if you create a private segment using your 
own segment and class names and then combine it with compiled 
code. Most compilers like to put the data area at the end of the 
section so a stack and heap can be allocated past the static data 
area. If your segments are assigned to the end, the compiler's 
run-time support system could smash your code when it is 
loaded. The CLASS statement can be used to put everything in 
the desired order. 


If your program contains only assembly language, be aware that 
some versions of the Microsoft assembler output the segments to 
the linker in alphabetical order by segment name instead of in the 
order they were defined. 


Consequently, the first class name seen by Plink86p/us ends up 
being the class name given to the segment whose name sorts 
first alphabetically. Segments in that class are then allocated first 
in memory. To get the correct order, rename your segments or 
use the CLASS statement to define the order. 


j 

| Use the DUMP utility to view the order of segment definitions іп 

| object files. For example, DUMP TEST.OBJ INCLUDE SEGDEF to 
print the segment definition records from the object file 
TEST.OBJ. 
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Addressing Bugs 


The Intel object format provides a variety of ways for a module to 
make external references to public symbols. Most of these 
methods can be generated by the assembler, but it’s easy to get 
something different than what you wanted and cause Plink86p/us 
to generate bad code. 


The generation of external references depends mainly on the 
location of the EXTRN statement since the segment:offset ad- 
dress of a symbol created with EXTRN is determined by the 
segment definitions currently in effect. This can cause problems 
under some circumstances. For example, if EXTRN is inside a 
SEGMENT definition, the assembler assumes that all references 
to the symbol will consist of a base register pointing to that 
segment followed by a relative offset. 


If a FAR call is then made to a symbol farther than 64kB away 
from the current code segment, Plink86p/us issues a warning 
message "Can't reach xxx” despite the FAR call because the 
linker was told to generate an offset from the current segment. 
To correct the problem, take the EXTRN statement outside the 
segment definition to allow PlinkB6p/us to examine the symbol 
definition and choose an appropriate base and offset address. 


Note: Address generation for most short calls is not affected by 
assembler quirks because the calls are offsets from the 
current CS. However, a warning message may be issued 
if the wrong segment is used. 
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The following files are included on the Plink86p/us distribution 


disk: 


FILE DESCRIPTION 


OVERLAY.LIB Object library containing run-time 
overlay loaders. When overlays are 
used, Plink86p/us selects the appropri- 
ate overlay loader from this file and 
includes it in the linked program. The 
overiay loader must be available on 
disk when a program containing over- 
lays is linked, but it doesn't have to be 
in the same file directory as the pro- 
gram being linked. 


Extra notes describing features added 
since the manual was published. 


UTILS «DIR» Contains utility programs 
CHECKSUM.EXE, DUMP.EXE, 
COMPARE.EXE and SYMPTABLE.EXE. 


CHECKSUM.EXE 
Utility program that validates the 
checksum of any .EXE file. 


COMPARE.EXE 
Utility program that performs a byte- 
by-byte comparison of two files. 


DUMP.EXE 
Utility progam that dumps files to the 
console or a disk file in a readable 

format. 


SYMTABLE.EXE 
Utility program that prints or deletes 
symbol tables created by the 
SYMTABLE statement. 


CONTINUED 
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DESCRIPTION 


Contains test files PLTEST.LIB and 
PLTEST.LNK. 


PLTEST.LIB 

Library file for the PLTEST program 
used in the initial Plink86p/us test 
procedures. 


PLTEST.LNK 

Link file for the PLTEST program 
used in the initial Plink86p/us test 
procedures. 


PLTEST «DIR» 


Contains overlay support files 
OVERLAY.LNK, OVTB.H, 
OVSTACK.ASM, OVUSERM.ASM and 
SAMPLE.ASM. 


OVERLAY.LNK 
Plib86 link file for OVERLAY.LIB. 


OVSTACK.ASM 
Support file containing assembler 
code for the OVERLAY.LIB routines 
$OVSAVE and $OVRESTORE. 

These routines allow stack mani- 
pulation for programs using RELOAD 
or TRACK. 


OVTB.H 
Assembly language header file that 
describes the PlinkB6p/us overlay 
loader table. 


OVUSERM.ASM 
Support file containing assembler 
code for the overlay loader's user 
support module. This code can be 
modified to change the behavior of 
the overlay loader to fit the require- 
ments of the application being linked. 


SAMPLE. ASM 
A simplified (and smaller) version of 
OVUSERM.ASM that can be used as the 
overlay loader's user support module 
for many application programs. 


OVERLAY «DIR» 
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Plink86p/us supports the Intel and Microsoft object module format 


mj standards and should work with any compiler or assembler that 
) produces .OBJ files. A useful guideline is that PlinkB6p/us should 
| link anything that the Microsoft and IBM linkage editors can link. 


The following compilers and assemblers are Known to work with 
Plink86p/us. The newest version supported is shown in parenthe- 
ses where appropriate: 


ө Arity Prolog 

o Aztec C 

o Computer Innovations CI-C86 

e Datalight C (ver. 2.20) 

e Lahey FORTRAN 77 (F77L version 2.0) 
e Lattice C (version 3.0, 3.10) 


T e Mark Williams C. Requires the version that outputs object 
files that are Microsoft/Intel-compatible. The version that 
uses the Mark Williams format will not work. 


o Metaware High C Compiler (version 1.3) 
o Microsoft Assembler (version 4.0) and IBM Assembler 


ө Microsoft BASIC Compiler and IBM BASIC Compiler (ver- 
sion 1.0). Overlays work, but you cannot chain to a pro- 
gram containing overlays. The chain function is non-stan- 
dard and does not use the DOS program loader. 


e Microsoft Business BASIC. Overlays work, but you cannot 
chain to a program containing overlays. The chain func- 
tion is non-standard and does not use the DOS program 
loader. 


/ е Microsoft C (version 3.0, 4.0) and IBM C 
o Microsoft and IBM COBOL 
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e Microsoft (version 4.0) and IBM Fortran. For older 
(pre-3.0) versions, use the NOSYMGROUP and DSAL- 
LOC statements. 


ә Microsoft Pascal (version 3.3). For older (pre-3.0) ver- 
sions, use the NOSYMGROUP and DSALLOC state- 
ments. 


e Nantucket Clipper DBASE Compiler 
ә Oregon PASCAL 


o Раѕт86 
e Ryan McFarland COBOL 


o Ryan McFarland FORTRAN 77. This compiler generates a 
private data segment for each module that may be in- 
cluded in the overlay structure by the statement “OVER- 

| LAY CODE, DATA”. 


o Wizard C 
о  Wordtech Dbase compiler 
| o WordTech Quicksilver Dbase III 


The following libraries are also known to work with Plink86p/us: 


o PforCe, Phoenix's Libraries for C 
o Windows for C 

o Blaise C Libraries 

o Hammer C Library 

o C - Food Smorgasbord 

e Greenleaf C Library 


Plink86p/us may work with compilers and assemblers not listed 
here, but there is no guarantee. Refer to Appendix H, 
“Troubleshooting and Problem Reporting" if PlinkB6p/us abso- 
lutely will not link object files generated by your compiler or 
assembler. 


ported 
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LEM REPORTING 


Technical support is happily provided for users who believe they 
have found a program bug in PlinkB6p/us. However, before 
reporting a possible bug, please read the following trouble- 
shooting tips to determine if your problem might be something 
else. 


The first rule of troubleshooting is not to panic. Since the linkage 
edit is the last step before you can run your program, it is only 
natural to assume your problem is with the linker. However, it is at 
least possible that the problem is really something you did to 
yourself. Another possibility is a bug in your compiler or operating 
system. 


If your programs will not link at all, check the warning or error 
messages that Plink86p/us generates when problems are encoun- 
tered. These messages explain problems such as syntax and 
keying errors or disk and file errors as they are encountered 
during command input and during the linkage edit. They also 
provide insight to programming problems such as symbol and 
overlay structure errors. 


If your programs link but you can't get the linked program to run 
properly, one or more of the following tips might help you: 


o Don't begin with a complicated overlay structure. Get 
your program working first without overlays (if it will fit into 
memory) and then add overlays one at a time so you will 
know when a new bug is introduced. 


o Initially, work exclusively with whatever high-level lan- 
guage you are using. Avoid adding assembly language if 
possible until the first test version of your program is run- 
ning. 
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o Do not mix and match object files from different compil- 
ers. Unlike mainframe compilers, microcomputer compil- 
ers are often incompatible with each other. Plink86p/us 
will link the programs for you and tell you about address- 
ing problems, but there is no way for the linker to know if 
the run-time systems of the two languages can coexist. 


ә |f your program is very large, try stubbing out parts of it to 
make a non-overlaid version fit. This strategy also means 
you won't be trying your first link the week before your 
deadline. 


o For Microsoft FORTRAN and Pascal versions (all pre-ver- 
sion 3.2), use the Plink86p/us DSALLOC statement. If 
DSALLOC is omitted, you will probably get strange mes- 
sages about stack overflows when you run the program, 
or the computer might hang up completely. You may also 
have to use the NOSYMGROUP statement to correct 
bugs in versions 1.x and 2.x of those compilers. 


о Is your overlay structure valid? Use the DEBUG statement 
to display a console message each time an overlay is 
loaded. You may be able to tell where the program is 
when it crashes. 


о Use the Plib86 library manager to produce a global cross- 
reference of your program to see if the calling sequences 
make sense. And finally, get the Pfix86p/us debugger. It 
can debug overlaid programs and show you what is hap- 
pening in your linked program. 


Your first task when you call to report a problem is to convince us 
that Plink86p/us is at fault. The linkage edit is the last step in your 
programming process, but it is not always the step that's causing 
a problem when you try to link the program. 


Be prepared to provide specific and detailed information about 
your problem. The problem might be from something you did or 
didn't do, and it might also be a compiler or operating system 
bug. The more information you can provide, the easier it is to 
isolate the problem. Keep a current copy of the MAP A report 
handy when you call. 
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If you mail us a problem report, please identify the manufacturer 

and version of the compiler or assembler you are using and 

describe the problem in as much detail as possible. Include a 

description of the input you are trying to use and where your 

object files came from. If it will help solve the problem, send 

diskette copies of the input, object and library files. Describe the E 
problem and be sure to include specific instructions for running 

the software and making the error condition occur. Source files 

| are usually not required. 


We will sign non-disclosure agreements if you desire and return 
| the diskettes to you when the problem is resolved. 


1 A word about bugs: 


| Like any significant piece of software, there definitely are some 
bugs remaining in Plink86p/us. You are most likely to run into 
them if you attempt to make Plink86p/us do something that 
wasn't anticipated by its designers and isn't being done else- | 
where. | 


Plink86p/us is updated frequently. Program updates are available 

for a reasonable cost, or you will receive a free copy if you are | 
the first to report a new bug. If we are unable to link your program | 
at all, you will receive a complete refund for the cost of the 
Plink86p/us software (within 30 days of purchase). | 


Again, please attempt to resolve problems in your program i 
before assuming a bug in Plink86p/us is involved. Even if you j 
cannot resolve the problem, at least you will be well-versed in its i 
symptoms when you call. 


TECHNICAL SUPPORT (617) 769-8310 


Phoenix Technologies Ltd. 
320 Norwood Park South, Norwood, MA 02062 
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APPENDIX I - PLINK86PLUS VERSION NOTES 


This appendix summarizes the differences between Plink86p/us | 
Version 2.2 and previous versions of Plink86p/us and Plink86. i 


Version 2.2 Statements vs. Previous Plink86p/us Versions 


CACHE Now supports three types of overlay 
cache: regular DOS memory (as before), 
extended (80286 protected mode) 
memory, and expanded (Lotus-intel— ' 
Microsoft bank-switched) memory. | 
The Cache type is specified as REGULAR, 
EXTENDED or LIM, such as CACHE ! 
EXTENDED. Only one type сап be | { 
specified per statement, but multiple | ) 
statements can allow a program to set ) 
ир the best possible cache for the | 
hardware it is used on. | 
Cache size and program size can now be | 
specified as 16-byte hex paragraphs (the i 
default), as kilobytes (k) or as a per- F 
centage (96). Per cent can also be 
specified with a leading 'p' as before. i 


COMPATIBLE | The comment marker is now a pound { 
sign ‘#' instead of a percentage sign '96'. | 
This was done to make use of '%' in the ! 
CACHE statement. The COMPATIBLE ; 
statement causes Plink86p/us to use '96' ! 
as the comment marker for compatibility 
with link files created for earlier 
Plink86 plus versions. | 
MTABLE Outputs object module names to the . 
symbol table instead of file names. à 
Previous versions output the module name ( 
by default. Now а stripped version of the 
filename is output as the default. MTABLE 
outputs the module name as before. 
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STATEMENT DESCRIPTION 
SSS 


NOBELL 
NOPUBLICS 


NOTYPCHECK 


NOVECTOR 
TRACK 


WORKFILE 


Overlay Loader Compatibility: The Plink86p/us overlay loader is 
not compatible with earlier Plink86p/us and Plink86 versions. 
Programs cannot link successfully under Version 2.2 when an 
outdated OVERLAY.LIB version is used. Refer to the file OVER- 
LAYNOVTB.H on the Plink86p/us distribution disk for overlay table 
format details. 


Suppresses beeps that sound when 
Plink86 plus error messages are displayed. 


Specifies symbols that are not globally 
accessible after an object file merge. 


Disables TYPDEF record processing as 
required for linking large programs com- 
piled with the Intel PL/M or Microtech 

Research Professional Pascal compilers. 


Effectively enables NEVER for all public 
symbols in a selected file or library. 


Effectively enables RELOAD for selected 
symbols only. 


Specifies a file name other than the 
default PLINK86.WRK and optionally a 
раш for the Plink86 p/us temporary work 
ile. 


To determine the OVERLAY.LIB version, dump the module VER- 
SION in OVERLAY.LIB for a list of Plink86p/us versions the library is 
compatible with (DUMP OVERLAY.LIB MOD VERSION). If VER- 
SION is not even present, the OVERLAY.LIB in question is a 
Plink86 library that will not work with Plink86p/us. 


Library Page Size: OVERLAY.LIB is now built with a smaller page 
size, allowing the same information to reside in a smaller library 
file. (To save space with libraries you create, use the Plib86 
BSIZE statement, such as PLIB86 BUILD X FILE Y,Z BSIZE 10H to 
build a library using 16 bytes per page instead of the default 512 
bytes.) 
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Extended Memory Allocation: Plink86p/us performs full extended 
memory allocation using the same allocation mechanism used by 
VDISK. Applications can access extended memory independent 
of the overlay manager. Note that the overlay manager takes 

over Interrupts 19h, 20h, 21h and 23h. | 


Networking Compatibility; OVUSERM.ASM is now set up for the . 
Novell network by default. To invoke support for the ViaNet 
network instead, assemble OVUSERM.ASM with the VIANET vari- 
able set to ‘1’. 


| OVUSERM.ASM now includes support for multiple copies of a 
A single executable file running across a NETBIOS standard net- 
| work. This support is invoked by assembling OVUSERM.ASM with 
the conditional variable MULTICOPY set to ‘true’. Note that ‘0x20’ 
is now the default open mode for overlay files under DOS 3.x. 
This is the standard shared open mode defined by NETBIOS. For 
DOS 2.x, '0' is used as before. | 


ЕСАСНЕ Statement: CACHE EXTENDED replaces the ЕСАСНЕ 
statement. However, ECACHE remains in the system for now to 
maintain compatibility with previous versions. 


Version 2.2 Statements vs. Plink86 Version 1.49 


) 
STATEMENT | DESCRIPTION | 


) 
АШОСАТЕ Automatically allocates modules from 1 
specified libraries to the overlay structure ) 
as required. f 
CACHE . Creates an overlay cache in regular DOS b 
memory, in extended memory, or in | 

expanded memory. 


N- COMPATIBLE | The comment marker is now a pound | 

| sign “#' instead of a percentage sign 4 
‘%'. This was done to make use of %” У 
in the CACHE statement. The 

| COMPATIBLE statement causes Plink86p/us 

to use “%” as the comment marker for 

я. compatibility with link files generated by 

( ж Plink86. 


~ 
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STATEMENT DESCRIPTION 
_————— Т ы 
GLOBALS Selects public symbols to include in the 
symbol! table. 


LOWERCASE | Now forces all symbol names and identi- 
fiers to lower case. In Plink86, 
LOWERCASE forced only lower case 
characters to lower case. Upper and 
lower case are now accepted freely mixed 
by default. 


MTABLE Outputs object module names to the 
symbol table instead of file names. 
NOBELL Suppresses beeps that sound when 
Plink86p/us error messages are displayed. 
NOPUBLICS Specifies symbol that are not globally 
accessible after an object file merge. 
NOTYPCHECK | Disables TYPDEF record processing. 


NOVECTOR Ee e, sets NEVER for selected files 
only. 
OUTPUT Now allows object file merging. 


PRELOAD Loads specified overlay sections into 
memory before passing control to the 
user program. 

RELOAD Reloads overwritten overlays aotomatically 
as required by the program. 


| 
| 
| 


rsion Notes 
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Note for Plink86 Users 
Plink86p/us is case sensitive. Check your Plink86 link files for the 
following "gotcha's": 


e OVERLAY statement: overlay code, data = overlay 
CODE DATA 


o MODULE statement: module test = module TEST | | 
o CLASS statement: class prog = class PROG 


o DEFINE statement: define = error = 100:10 vs define 
ERROR = 100:10 i 


o А library with lower case symbols and an upper case in- ! 
dex. 


o Assembler combined with a case sensitive high-level lan- > 
guage. b 


In all cases, adding UPPERCASE or LOWERCASE to the link file 
will solve the initial incompatibilities. 
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TERM 


Absolute Symbol 


Ancestor 


Cache 


Class 


Common Block 


Descendants 


DEFINITION 


A symbol that names a value that is a con- 
stant (i.e., an absolute address). 


The last section defined prior to the beginning 
of the overlay area. The “ancestors” of an 
overlay consist of the ancestor, the ances- 
tor’s ancestor, etc. until a resident section is 
reached. The number of ancestors for an 
overlay is equal to its level number. 


A reserved portion of memory (if available) 
where overlay sections are loaded for fater 
insertion in the overlay structure. Memory 
caching speeds execution because the over- 
lays are not loaded from disk each time the 
program accesses them. 


Ап intel 8086 categorical segment organi- 
zation that provides a method for moving 
segments to a specified section without nam- 
ing each segment to be moved. All segments 
are assigned a class by the compiler or as- 
sembler. Typically, class is used to define for 
the linkage editor the order that segments 
should be allocated memory. 


Segments created by Fortran and other com- 
pilers that provide an antiquated method for 
sharing data areas among modules by over- 
lapping common blocks with other common 
blocks from different modules. Modern lan- 
guages like C and Pascal use public symbols 
for this purpose. 


All sections of a program that have a given 
section as an ancestor. 
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Executable File 


External Symbol 


Far 


Fixup 


Group 


Input File 


Glossary-2 


_ L CE 


isk 
The output of the linkage editor in a .EXE diS 


file that contains a program that can be 8X8- 
cuted by the operating system. 


A public symbol that is not defined inside 8 
module that references it, such as a symbol 
that is defined in the compiler's run-time 
support library and referenced by a module of 
the application program being linked. This 
symbol is "external" to the module referenc- 
ing it. 


Memory address or reference that consists of 
a segment and an offset that can access any 
memory location. 


Linkage editor function that supplies a value 
to an external symbol reference inside a 
linked module when the module containing 
the symbol definition is found. 


An Intel 8086 addressing classification that 
defines a collection of segments that will be 
accessed by the same segment register. 
Group is a logical concept used only for ad- 
dressing. Segments in a group do not require 
adjacent memory locations so long as they 
remain within a 64КВ memory area. Seg- 
ments from different groups can be mixed 
together in the same section, and segments 
from the same group can be distributed 
among several sections. 


.OBJ file created by the compiler that is input 
to the linkage edit. 


ка; 


Level Number 


Library 


Library Search 


Memory Map 


Module 


Near 


Object File 


Number assigned to each section of a pro- 
gram. Resident sections are assigned a level 
of zero. When a BEGINAREA statement is 
encountered, the level number is increased 
by one, and decreased by one when the EN- 
DAREA statement is encountered. 


.LIB compiler-generated object file containing 
two or more modules that can be individually 
selected by the linkage editor as required. 


Plink86p/us function commonly used to ac- 
cess required modules only from a library. 


Report that describes the Plink86p/us linkage 
edit Output, including assigned memory ad- 
dresses for groups, sections, segments and 
symbols. 


A unit of source or object code. Typically, a 
compiler or assembler translates a module of 
source code into a module of object code. 


Memory address or reference consisting of a 
single offset word that can access any mem- 
ory location in the current 64kB segment 


only. 


.OBJ file created by the compiler (or assem- 
bler) to store the compiled program. 


ЬЬ ——À 


the 
Output File .EXE file created by Plink86p/us to store 
linked program. 


| Overlay A section that shares all of part of its memory 
with one or more other sections. Overlays 
reduce the program’s memory requirement 
because they are loaded to memory as ГӨ- 
quired by the executing program and over- 
write other overlays that were using the same 
space. 


Аала 
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Overlay Loader Phoenix library code included in the linked 
program by the linkage editor to load required 
overlay sections automatically during the user 
program's execution. 


Pfix86p/us Phoenix Technologies Ltd. symbolic de-bug- 
ging program. 


Plib86 Phoenix Technologies Ltd. library manage- 
ment program. 


Plink86p/us Phoenix Technologies Ltd. linkage editor and 
overlay management program. 


Private Segments Segments that cannot be combined to oc- 
| сиру adjacent memory locations. Private seg- 
| ments are normally addressed by setting а 

segment register to the front of the called 
segment. 


| Public Segments Segments that can be combined with other 
| segments of the same name to occupy adja- 
cent memory locations. The combined seg- 
ment is normally accessed by putting its 
paragraph address into a segment register. 


| 
| 
! 
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Public Symbol 


Relative Symbol 


Section 


Segment 


Symbol 


A symbol whose relative address is de-sig- 
nated by the compiler to be available for 
modules other than the module that defines 
it. Public symbols are used to share proce- 
dures and variables among different mod- 
ules. If the public symbol is a relative symbol, 
the contents of the memory location de- 
scribed are accessible by other modules. 


A symbol that names a value relative to a 
segment, such as the absolute address of a 
segment plus 50 bytes. 


Load module portion of a .EXE or .OVL file 
that is loaded from disk to memory as a sin- 
gle unit. Typically, the section containing the 
main program modules is loaded when the 
program is executed, and other sections are 
loaded as overlays when required during exe- 
cution. Overlays are sections that share 
memory with other sections. 


A piece of code or data that is manipulated 
by the linkage editor as an indivisible unit. A 
module consists of segments. The linkage 
editor determines how much memory each 
segment of each module requires and where 
in memory to put it. Segments that address 
code in other segments are fixed up by the 
linkage editor after the segment addresses 
have been selected. 


The assigned name for a value that is a con- 
stant (absolute symbol) or the address of a 
piece of code or data somewhere in the pro- 
gram (relative symbol). Symbols designated 
as "public" can be accessed by modules 
other than the module where they are de- 
fined. 
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ne 
Symbol Table Report appended to a program f'e By 
Plink86plus for use with Pfix86plus, the PhO? 

nix Technologies Ltd. symbolic de- bugging 

program, and with Pfinish, the Phoenix Tech- 

nologies Ltd. program performance analyzer. 
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Command Format Summary, 9-8 
COMMAND FORMATS, 3-1 

Command Line Input, 3-3 

COMMAND REFERENCE, 9-1 

Command Syntax Errors, 10-9 

Comment Marker, 3-11, 4-21 

Compare Files, 4-27 

COMPARE.EXE Utility, 4-27, 9-83 
COMPATIBLE Statement, 4-21, 9-23 


м 


7 т=н 


Compilers Supported, 1-2, G-1 
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DOS 3.x Memory Management, 4-19 
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Dump Files, 4-28 
DUMP.EXE Utility, 4-28, 9-84 
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ENDAREA Statement, 5-6, 9-28 
ERROR AND WARNING MESSAGES, 10-1 
Examples, 8-4 

EXCLUDE (Plib86 Statement), 11-18 
Exclude Symbols from Table, 6-4 
EXPLODE (Plib86 Statement), 11-19 
Expanded Memory Cache, 5-17 
Extended Memory Cache, 5-17 
External Symbol Addressing, 6-7 
External Symbol References, 6-7 
Extract a Single Library Module, 11-8 
Extract an Entire Library, 11-9 
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File Names, 3-10 

FILE (PlibB6 Statement), 11-21 
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Finding the Object Files, 4-8 
Finding the Overlay Files, 5-27 


Generate Memory Map Reports, 7-2 
GLOBALS Statement, 6-4, 9-31 
Group Assignment, 4-17 

GROUP Statement, 4-17, 9-33 


HEIGHT (Plib86 Statement), 11-23 
HEIGHT Statement, 7-6, 9-34 
How Overlays Work, 5-10 

How Plib86 Works, 11-4 

How Plink86p/us Works, 1-4 
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n 


Manual Segment Ordering, 4-14 
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Multiple Overlay Areas, 5-11 
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NEVER Statement, 5-30, 9-49 
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NOLOCALS Statement, 6-4, 9-52 
NOPUBLICS Statement, 4-10, 9-53 
NOSYMGROUP Statement, 4-22, 6-7, 9-54 
NOTYPCHECK Statement, 4-24, 9-55 
NOVECTOR Statement, 9-56 

NWIDTH (Plib86 Statement), 11-33 
NWIDTH Statement, 7-6, 9-57 
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S SEARCH (Plib86 Statement), 11-34 

SEARCH Statement, 4-6, 9-67 
Section Organization, 4-12 

| Section Report Headings, 7- 4 

h SECTION Statement, 4-12, 5-6, 9-68 

| SECTION INTO, 5-25 
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Phoenix Technologies Ltd. 


MONEY WILL BE REFUNDED. 


Phoenix provides this program and licenses its 
use. You assume responsibility for the selection 
of the program to achieve your intended results, 
and for the installation, use and results obtained 
from the program. 


LICENSE - PLP16154 


You may: 
use the program on a single machine; 

copy the pegam into any machine readable 
or printed form for backup or modification 
purposes in support of your use of the pro- 
gram on the single machine. (Certain pro- 
ce however, may include mechanisms to 
imit or inhibit copying. They are marked 
"copy protected"). 


c. modify the program and/or merge into an- 
other program for your use on the single ma- 
chine (Ату portion of the program merged 
into another program will continue to be 
subject to the terms and conditions of this 
Agreement.); and, 


d. transfer the program and license to another 
party if the other party agrees to accept the 
terms and conditions of this Agreement. If 
you transfer the program, you must at the 
same time either transfer all copies whether 
in printed or machine-readable form to the 
same party or destroy any copies not trans- 
ferred; this includes all modifications and 

ortions of the program contained or merged 
into other programs. 


You must reproduce and include the copyright 
notice on any copy, modification or portion 
merged into another program. 

YOU MAY NOT USE, COPY, MODIFY, OR 
TRANSFER THE PROGRAM, OR ANY COPY, 
MODIFICATION OR MERGED PORTION IN 
WHOLE OR IN PART. EXCEPT AS EXPRESSLY 
PROVIDED FOR IN THIS LICENSE. 


IF YOU TRANSFER POSSESSION OF ANY COPY, 
MODIFICATION OR MERGED PORTION OF 
THE PROGRAM TO ANOTHER PARTY YOUR LI- 
CENSE IS AUTOMATICALLY TERMINATED. 


TERM 

The license is effective until terminated. You 
may terminate it at any other time by destroying 
the program together with all copies, modifica- 
tions and merged portions in any form. It will 
also terminate upon conditions set forth else- 
where in this Agreement or if yon fail to comply 
with any term or condition of this Agreement. 
You agree upon such termination to destroy the 
,program together with all copies, modifications 
гапа merged portions in any form. 


LIMITED WARRANTY 
a. HIS PROGRAM IS PROVIDED “AS IS ” WITH- 


а. 
Ь, 


WT WARRANTY OF ANY KIND, EITHER EX- 


RRESSED OR IMPLIED, INCLUDING, BUT NOT 


eee MITED TO THE IMPLIED WARRANTIES OF 


BS CHANTABILITY AND FITNESS FOR A PAR- 
QUALITY AND петт 


AT. 
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YOU SHOULD CAREFULLY READ THE FOLLOWING TERMS AND 
CONDITIONS BEFORE OPENING THIS DISKETTE PACKAGE. ОРЕМІ 
THIS DISKETTE PACKAGE INDICATES YOUR ACCEPTANCE OF THE 
TERMS AND CONDITIONS. IF YOU DO NOT AGREE WITH THEM, YOL— 
SHOULD PROMPTLY RETURN THE PACKAGE UNOPENED; AND YOU ме 


— 


— 


SOME STATES DO NOT ALLOW THE ЕХСІ.- 
SION OF IMPLIED WARRANTIES, SO Ths 
ABOVE EXCLUSIONS MAY NOT APPLY 1 
YOU. THIS WARRANTY GIVES YOU ӨРЕСІН 
LEGAL RIGHTS AND YOU MAY ALSO HAVE 
OTHER RIGHTS WHICH VARY FROM STATE Tu 
STATE. 

Phoenix does not warrant that the functions 
contained іп the program will meet your re- 
quirements or that the operation of the program 
will be uninterrupted or error free. 


However, Phoenix warrants the пакана) оп 
which the program is furnished, to be free from 
defects in materials and workmanship under 
normal use for a period of ninety (90) days from 
the date of delivery to you as evidenced by а 
copy of your receipt. 


LIMITATIONS OF REMEDIES 


Phoenix’s entire liability and your exclusive 

remedy shall be: 

l. the replacement of any diskette not meeting 
Phoenix's "Limited Warranty” and which is 
returned to Phoenix or authorized dealer 
with a copy of your receipt, or 

2. If Phoenix, or the dealer is unable to deliver 
a replacement diskette which is free of de- 
fects in materials or workmanship, you may 
terminate this Agreement by returning: the 
program and your money will be refunded. 


IN NO EVENT WILL PHOENIX BE LIABLE TO 
YOU FOR ANY DAMAGES, INCLUDING ANY 
LOST PROFITS, LOST SAVINGS OR OTHER IN- 
CIDENTAL OR COE UM OLEUM. DAMAGES 
ARISING OUT OF THE USE OR INABILITY TO 
USE SUCH PROGRAM EVEN IF PHOENIX OR 
AN AUTHORIZED DEALER HAS BEEN ADVISED 
OF THE POSSIBILITY OF SUCH DAMAGES, OK 
FOR ANY CLAIM BY ANY OTHER PARTY. 


SOME STATES DO NOT ALLOW THE LIMITA- 
TION OR EXCLUSION OF LIABILITY FOR INCI- 
DENTAL OR CONSEQUENTIAL DAMAGES SO 
THE ABOVE LIMITATION OR EXCLUSION MAY 
NOT APPLY TO YOU. 

GENERAL 

You may not sublicense, assign or transfer the 
license or the program except аз expressly pro- 
vided in this Agreement. Any attempt otherwise 
to sublicense, assign or transfer any of the 
rights, duties or obligations hereunder is void. 
This Agreement Will be governed by the laws of 
the Commonwealth of Massachusetts. 

Should you have any questions concerning this 
Agreement, you may contact Phoenix by writing 
to Phoenix Technologies Ltd., 320 Norwood 
Park South, Norwood, Massachusetts 02062 
YOU ACKNOWLEDGE THAT YOU uM т 
THIS AGREEMENT, омос M \ i 
AGREE TO BE [vw 
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All software on this diskette. whether in source or object form, is pro- 
prietary and may be used and copied only under the terms of the Phoenix 
Technologies Software License. This diskette is serialized and may be 
used only by the registered user. М may not be resold or transferred 
without the consent of Phoenix Technologies. Phoenix Technologies prod- 
uct names are trademarks of Phoenix Technologies Ltd.,| Norwood, | MA. 
© Copyright 1979, 1980, 1981, 1982, 1983, 1984, 1985, 1986, 1987. 
Phoenix Technologies Ltd. 

320 Norwood Park South, Norwood, MA 02062 


